Serialization-boundary marker for rows, collections and nullable fields
Zero-runtime marker for the serialization-safe shape at DB / HTTP / JSONB boundaries. Grep-able, ESLint-aware, no casts at call sites.
A serialization-boundary marker for values crossing DB rows, HTTP bodies, JSONB payloads and workflow inputs. It wraps any boundary shape: a collection, a nullable field, or a whole row type. Zero runtime cost, assignable both ways with the plain type, no casts at call sites.
declare const WIRE: unique symbol;
export interface WireMark {
readonly [WIRE]?: never;
}
export type Wire<T> = T | (T & WireMark);
Wire is a flavored type, not a branded one. The plain T member means Wire<T> and T accept each other without ceremony, including null, undefined and unknown, so generic helpers like findOne<R>(): Promise<Wire<R | null>> compile. null is exactly the shape that survives JSON.stringify.
The T & WireMark member is there for naming, not safety. It keeps TypeScript from resolving the alias away, so inferred exports emit Wire<Row> in .d.ts files and hovers.
The value doesn’t come from type-level enforcement. It comes from three places:
rg 'Wire<' is a complete, countable inventory of every serialization boundary in the codebase.type UserRow = Wire<{ … }> states the boundary in exactly one place.functype/prefer-list and functype/prefer-option skip everything inside a Wire<…> type argument. A ReadonlyArray or a T | null there is the declared wire shape, not a missed List or Option.import type { Wire } from "functype";
or
import type { Wire } from "functype/wire";
import type { Wire } from "functype";
// A whole row or DTO: every field inside is covered.
type UserRow = Wire<{
readonly id: string;
readonly email: string | null;
readonly tags: ReadonlyArray<string>;
}>;
// A collection.
type UserRows = Wire<ReadonlyArray<UserRow>>;
// A single field on an otherwise domain-shaped type.
type Invite = {
readonly id: InviteId;
readonly acceptedAt: Wire<string | null>;
};
// eslint.config.mjs — hold the enforcement, mark the boundaries
{
"functype/prefer-list": ["error", { "allowReadonlyArrays": false }],
"functype/prefer-option": "warn", // "error" once your boundary types are wired
}
// Declare the boundary once.
async function fetchUsers(): Promise<UserRows> {
return db.query("SELECT * FROM users").rows;
}
// Inside the pipeline, convert to List and Option for transformation.
const reachable = List(await fetchUsers())
.filter((u) => Option(u.email).isSome())
.map(enrich);
Both rules take wireTypes (default ["Wire"]). Add your own boundary alias name if you have one, or pass [] to turn the exemption off. Qualified references (functype.Wire<…>) are recognized.
In 1.9, Wire<T> meant ReadonlyArray<T>. In 1.10 it wraps any shape, so:
import type { Wire } from "functype";
// 1.9 wrote this as Wire<Row>, which meant an array of Row
type ClaimedDocs = Wire<ReadonlyArray<Row>>; // 1.10+
The break is loud, not silent: a Wire<Row> that meant an array fails to compile at the first .map or array assignment. The two exceptions are Wire<object> and Wire<any>, which accept an array under either meaning; search for them when upgrading.
List<T> / Option<T> first.Ask who reads the absence.
Option when your own code reads it. You branch on it, map it, or return it to code that does.Wire when something outside your code reads it, or when the absence is part of the format. That reader is a serializer, a driver, a schema library or a host API.Wire value turns it into Option if later code decides anything from it.Serialized shapes. Option doesn’t survive JSON.stringify, and drivers return null.
import type { Wire } from "functype";
type ChainRow = Wire<{
readonly id: string;
readonly entity_id: string | null;
readonly literal: string | null;
}>;
Three states: left out, cleared, set. This is the case where Option is wrong, not just awkward. A patch body’s field can be left out (keep the old value), sent as null (remove it) or sent with a value (replace it). Option<T> has two states, so converting loses the difference. prefer-option says so when one union, as a type alias’s body or a type-literal or interface member, holds both null and undefined, and when an optional member can also be null (a?: T | null). The message names both fixes, because a domain type written that way often only meant “may be absent”.
import type { Wire } from "functype";
type Clearable<T> = Wire<T | null | undefined>; // undefined: keep, null: remove, T: replace
const keep = <T>(next: Wire<T | undefined>, old: T): T =>
next === undefined ? old : next;
Types inferred from a schema. A type from z.infer, valibot or a decoder is the wire shape by definition. Wrap the alias, and convert a field to Option when code first decides something from it.
import type { Wire } from "functype";
type Given<T> = Wire<T | undefined>; // a tool input field that may be left out
Helpers that pass a wire value through. A row mapper that reads a nullable column and writes a nullable field decides nothing about the absence. An Option there only adds a conversion you undo.
import type { Wire } from "functype";
type Quantity = { readonly value: number; readonly unit: string };
const quantity = (
value: Wire<number | null>,
unit: Wire<string | null>,
): Wire<Quantity | null> =>
value === null || unit === null ? null : { value, unit };
Props and options objects. The caller writes <X a="v" />, so these are host shapes. prefer-option skips a?: T and a: T | undefined on a member or parameter by default.
A function result that code goes on to read is an Option. The driver returns a row or undefined, the function converts it once, and callers fold.
import { Option } from "functype";
type Entity = { readonly name: string };
const findByName = (
entities: ReadonlyArray<Entity>,
name: string,
): Option<Entity> => Option(entities.find((entity) => entity.name === name));
Wire on a domain type just to quiet the rule. Ask whether the value really crosses a boundary in this exact shape.Option inside a row or body type. It serializes as an object and doesn’t round-trip.Wire value that keeps flowing past the first function that decides something from it.