@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/routing/segment-keys.ts

@@ -0,0 +1,146 @@
+/**
+ * Segment key computation — the stable identity of a segment in the route tree.
+ *
+ * A segment key is the string that names a segment across the RSC/SSR/client
+ * boundary: it appears in the X-Timber-State-Tree header, the X-Timber-Segments
+ * header, SegmentOutlet props, the client segment cache, and (since TIM-1279)
+ * interception scoping.
+ *
+ * This module lives in `routing/` rather than `server/` because the keys are a
+ * property of the route tree itself — both the build-time scanner tree and the
+ * runtime manifest tree produce identical keys for the same directory, which is
+ * what lets a build-time value (an interception scope) be compared against a
+ * request-time matched chain.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+
+/**
+ * Segment node shape expected by computeSegmentKeys.
+ *
+ * Structurally satisfied by both `SegmentNode` (build time) and
+ * `ManifestSegmentNode` (request time) — keys depend only on the
+ * URL path and the segment classification, never on file payloads.
+ */
+export interface SegmentKeyInput {
+  urlPath: string;
+  segmentName?: string;
+  segmentType?: string;
+}
+
+/**
+ * Compute state-tree keys for a segment chain.
+ *
+ * Non-group segments use their urlPath as-is. Route groups accumulate
+ * ancestor group names to produce globally unique keys:
+ *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
+ *
+ * **An intercepting segment switches the chain to name accumulation for good.**
+ * A children-path interception (TIM-1280) puts an intercepting node and its
+ * descendants into the *main* rendered chain, and their `urlPath`s are not
+ * URLs: interception adds no URL depth, so `app/(browse)/(...)[artistSlug]/[year]`
+ * carries `/` and `/[year]`. Keyed by urlPath the intercepting node would
+ * collide with its own owner, and `[year]` with any top-level `[year]` route —
+ * so a client that had one mounted would reuse the wrong cached layout. The
+ * switch is sticky rather than per-node because the *descendants* are where
+ * the false URLs are; the intercepting node alone is not the problem.
+ *
+ * This is the single source of truth for segment keys — used by the
+ * element builder (skip decisions, SegmentOutlet props), segment info
+ * (X-Timber-Segments header), the client cache/state tree, and
+ * interception scoping (`routing/interception.ts`).
+ */
+export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
+  const keys: string[] = [];
+  let prevKey = '';
+  let insideIntercepting = false;
+
+  for (const segment of segments) {
+    if (segment.segmentType === 'intercepting') insideIntercepting = true;
+    if (segment.segmentType === 'group' || insideIntercepting) {
+      const base = prevKey === '/' ? '' : prevKey;
+      const key = `${base}/${segment.segmentName}`;
+      keys.push(key);
+      prevKey = key;
+    } else {
+      keys.push(segment.urlPath);
+      prevKey = segment.urlPath;
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Compute tree paths for a segment chain — the directory path of each segment
+ * with slots elided, e.g. `app/(browse)/feed` → `/(browse)/feed`.
+ *
+ * This is `computeSegmentKeys` with the group branch applied to *every*
+ * segment rather than only to groups. That one difference is the whole point:
+ * `computeSegmentKeys` resets to `urlPath` at each URL-visible segment, so
+ * `(browse)/feed` and `(landing)/feed` both key as `/feed`. Two directories
+ * that render different layouts must not share an identity.
+ *
+ * Used for interception scoping (`routing/interception.ts`), where the
+ * question is "does this route pass through *that* directory?" — not "does it
+ * render this URL?". Not interchangeable with `computeSegmentKeys`: the state
+ * tree is keyed by URL on purpose, because the client caches by URL.
+ */
+export function computeSegmentTreePaths(segments: SegmentKeyInput[]): string[] {
+  const paths: string[] = [];
+  let prev = '';
+
+  for (const segment of segments) {
+    const name = segment.segmentName ?? '';
+    if (!name) {
+      // The app root — no directory name of its own.
+      paths.push('/');
+      prev = '/';
+      continue;
+    }
+    const base = prev === '/' ? '' : prev;
+    const path = `${base}/${name}`;
+    paths.push(path);
+    prev = path;
+  }
+
+  return paths;
+}
+
+/**
+ * The directory names a tree path is built from — `/` is none, `/feed/(a)` is
+ * `['feed', '(a)']`.
+ *
+ * The inverse of the walk above, and it lives beside it so the format is
+ * stated once: `findChainByTreePath` (`server/children-interception.ts`) walks
+ * these names back down the tree to the directory the path addresses, and
+ * `treePathDepth` counts them. Both are readings of the same string, and a
+ * reader that disagreed with the producer about what separates two names
+ * resolves an interception to the wrong node or to none.
+ */
+export function treePathNames(treePath: string): string[] {
+  return treePath === '/' ? [] : treePath.slice(1).split('/');
+}
+
+/**
+ * How many directories a tree path names — `/` is 0, `/feed` is 1,
+ * `/feed/(a)` is 2.
+ *
+ * Two tree paths on a single rendered chain are strictly nested, so on that
+ * chain depth orders them totally — which is what makes it usable as "the
+ * deeper of these two directories" wherever a route passes through both
+ * (`routing/interception.ts`).
+ */
+export function treePathDepth(treePath: string): number {
+  return treePathNames(treePath).length;
+}
+
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export function computeSlotKey(parentSegmentId: string, slotName: string): string {
+  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
+  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
+  return `${prefix}/${name}`;
+}

package/src/routing/slot-placement.ts

@@ -0,0 +1,97 @@
+/**
+ * Parallel slot placement.
+ *
+ * One rule: a slot is resolved only for a segment on the **matched route
+ * chain**, and a slot's own subtree is never on that chain. So a slot declared
+ * anywhere inside another slot's subtree can never render, and is rejected at
+ * build time rather than left as a directory the author will keep editing.
+ *
+ * See design/07-routing.md §"Parallel Routes".
+ */
+
+import type { SegmentNode } from './types.js';
+
+/**
+ * Reject every parallel slot that no renderer reaches.
+ *
+ * **Where slots are resolved.** Two places read `segment.slots`, and both walk
+ * the main route chain: `route-element-builder.ts` (the RSC render) and
+ * `tree-builder.ts`. Neither is reachable from inside a slot. The slot's own
+ * subtree is rendered by `slot-resolver.ts`, which walks the slot's matched
+ * chain to apply that chain's layouts, error boundaries and access gates
+ * (`wrapWithIntermediateSegments`, `wrapWithLayout`) and never reads `.slots`
+ * on any of those nodes. So `app/feed/@modal/photo/@side/page.tsx` and
+ * everything below it is dead: the file is scanned, typed, code-split and
+ * shipped, and no request can render it.
+ *
+ * That is the TIM-1278 failure — a directory that silently never renders —
+ * and the reason it is a build error rather than a documented limit is that
+ * nothing at request time can report it. A slot that does not match renders
+ * `default.tsx` or `null`, which is exactly what a slot the resolver never
+ * looked at also produces, so the author sees the *designed* behaviour of a
+ * non-matching slot and has no signal to distinguish it from a slot that
+ * cannot match at all.
+ *
+ * **Interception is incidental.** TIM-1311 arrived as
+ * `feed/@modal/(.)photo/@side`, and the interception contributes nothing: the
+ * identical `feed/@modal/photo/@side` never renders either, for the same
+ * reason and with no marker anywhere. Rejecting only the intercepting spelling
+ * would have drawn a line the author cannot see from the directory names.
+ *
+ * The children-path interception shape is **not** affected and must not be:
+ * its intercepting node joins the main chain (`server/children-interception.ts`
+ * splices `[…owner ancestors, interceptingNode, …descendants]` into an ordinary
+ * `RouteMatch`), so `route-element-builder.ts` resolves slots on it and below
+ * it exactly as it does for any other chain segment. `(browse)/(...)photo/[id]/@side`
+ * renders; `feed/@modal/(.)photo/@side` does not. The discriminator is the slot
+ * boundary, which is what this walk tracks — not the marker.
+ */
+export function validateSlotPlacement(root: SegmentNode): void {
+  walkForSlotPlacement(root, '', null);
+}
+
+/**
+ * `enclosingSlotPath` is the `app/`-relative path of the nearest slot at or
+ * above `node`, or null on the main chain. It is carried rather than recomputed
+ * so the error can name the slot that swallows the offender — "this is inside
+ * @modal" is the part of the diagnosis the author cannot see from the offending
+ * path alone.
+ */
+function walkForSlotPlacement(
+  node: SegmentNode,
+  path: string,
+  enclosingSlotPath: string | null
+): void {
+  for (const [slotName, slotNode] of Object.entries(node.slots)) {
+    const slotPath = path ? `${path}/@${slotName}` : `@${slotName}`;
+    if (enclosingSlotPath !== null) {
+      throwNestedSlot(slotPath, enclosingSlotPath);
+    }
+    walkForSlotPlacement(slotNode, slotPath, slotPath);
+  }
+
+  for (const child of node.children) {
+    walkForSlotPlacement(
+      child,
+      path ? `${path}/${child.segmentName}` : child.segmentName,
+      enclosingSlotPath
+    );
+  }
+}
+
+function throwNestedSlot(slotPath: string, enclosingSlotPath: string): never {
+  throw new Error(
+    `Build error: parallel slot nested inside another parallel slot.\n` +
+      `  Directory: app/${slotPath}\n` +
+      `  Inside:    app/${enclosingSlotPath}\n` +
+      `A parallel slot is resolved only for a segment on the matched route chain, and a ` +
+      `slot's own subtree is never on that chain — the slot resolver walks the slot's ` +
+      `matched chain to apply its layouts, error boundaries and access gates, and never ` +
+      `looks at slots declared inside it. So app/${slotPath} and everything below it can ` +
+      `never render, and no request-time signal can tell you: an unreachable slot ` +
+      `produces exactly what a slot that simply did not match produces.\n` +
+      `Declare the slot on a segment of the main route chain instead, or move its pages ` +
+      `into app/${enclosingSlotPath}'s own subtree.\n` +
+      `See design/07-routing.md §"Parallel Routes".`
+  );
+}

package/src/routing/types.ts

@@ -96,12 +96,6 @@ export interface SegmentNode<TFile = RouteFile> {
   middleware?: TFile;
   access?: TFile;
   route?: TFile;
-  /**
-   * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.
-   * Discovered by the scanner like middleware.ts and access.ts.
-   * See design/07-routing.md §"params.ts Convention File"
-   */
-  params?: TFile;
   error?: TFile;
   default?: TFile;
   /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */

package/src/routing/walkers.ts

@@ -49,6 +49,12 @@ export interface CollectLeafRoutesOptions {
  *   entries (the build report deduplicates by URL afterward).
  * - Parallel slots are skipped unless `includeSlots: true` (slots
  *   share their parent's URL and are not addressable on their own).
+ * - Intercepting subtrees are skipped unconditionally. They render only
+ *   on soft navigation and add no URL depth, so their computed `urlPath`s
+ *   are not addresses — listing them would advertise routes (`/[year]`)
+ *   that no request can reach. This matches every other consumer of the
+ *   tree that produces URLs: the sitemap generator, the static generator,
+ *   prerendering and the prebuilt-payload builder all skip them too.
  * - Result is sorted by `urlPath` for deterministic output.
  */
 export function collectLeafRoutes<TFile>(
@@ -68,6 +74,8 @@ function walk<TFile>(
   result: LeafRoute<TFile>[],
   includeSlots: boolean
 ): void {
+  if (node.segmentType === 'intercepting') return;
+
   const currentChain = [...chain, node];
   const path = node.urlPath || '/';
 

package/src/schema-bridge.ts

@@ -5,8 +5,17 @@
  * This module is the single source of truth for:
  * - StandardSchemaV1 interface (subset of the Standard Schema spec)
  * - validateSync() helper
- * - fromSchema() — bridge from Standard Schema to Codec<T>
- * - fromArraySchema() — bridge for array-valued codecs
+ * - fromSchema() — search-param bridge; scalar shape first, array second
+ * - fromArraySchema() — same loop, array shape first
+ * - fromCookieSchema() — scalar shape only; a cookie has no array shape
+ * - fromParamSchema() — route params; throws on failure (invalid param → 404)
+ *
+ * One parse loop, four candidate orders. Which shapes a bridge offers, and
+ * in what order, is the ONLY thing that differs — see §"Shape tolerance"
+ * below and in design/23-search-params.md. `serialize` is deliberately NOT
+ * shared: `null` means "omit the key" for a search param and "delete the
+ * cookie" for a cookie, so unifying it silently changed what
+ * `cookie.set([])` did (TIM-1352).
  *
  * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
  * and @timber-js/app/cookies for convenience. The canonical import is
@@ -122,18 +131,21 @@ export function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T
  * @param fieldName - used in error messages
  * @param value - the codec or schema to resolve
  * @param mode - 'param' uses fromParamSchema (throws on parse failure),
- *               'search' uses fromSchema (falls back to default on failure)
+ *               'search' uses fromSchema (falls back to default on failure,
+ *               tolerant of the repeated-key array shape),
+ *               'cookie' uses fromCookieSchema (same, minus the array shape,
+ *               which a cookie value cannot have)
  */
 export function resolveCodecOrSchema(
   fieldName: string,
   value: unknown,
-  mode: 'param' | 'search' = 'search'
+  mode: 'param' | 'search' | 'cookie' = 'search'
 ): Codec<unknown> {
   if (isCodec(value)) return value;
   if (isStandardSchema(value)) {
-    return mode === 'param'
-      ? fromParamSchema(fieldName, value)
-      : (fromSchema(value) as Codec<unknown>);
+    if (mode === 'param') return fromParamSchema(fieldName, value);
+    if (mode === 'cookie') return fromCookieSchema(value) as Codec<unknown>;
+    return fromSchema(value) as Codec<unknown>;
   }
   throw new Error(
     `[timber] Field '${fieldName}' is not a valid codec or Standard Schema. ` +
@@ -146,51 +158,169 @@ export function resolveCodecOrSchema(
 // fromSchema — bridge from Standard Schema to Codec<T>
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Shape tolerance — the shared parse loop for both bridges
+//
+// A URL value is `string | string[] | undefined`, but a schema is written
+// against ONE of those: `z.string()` wants `'a'`, `z.array(z.string())`
+// wants `['a']`. Nothing in Standard Schema says which — `~standard.types`
+// exists at the type level only, and probing at runtime is not reliable
+// (design/23-search-params.md §"Shape tolerance"). So a bridge tries BOTH
+// shapes rather than committing to one and discarding the value when it
+// guessed wrong.
+//
+// Each bridge only chooses WHICH candidates, and in what order. The first
+// candidate is always the shape that bridge already passed, so nothing that
+// parses today changes meaning; a later one is reached only where the old
+// code fell through to the default. `fromCookieSchema` offers ONE candidate,
+// because a cookie has no array shape at all.
+// ---------------------------------------------------------------------------
+
+/**
+ * The scalar shape, and only it. A value that cannot be repeated — a cookie —
+ * has no array shape to tolerate, so its bridge stays exactly where it was.
+ */
+function scalarOnly(value: string | string[] | undefined): unknown[] {
+  return [Array.isArray(value) ? value[0] : value];
+}
+
+/** Candidate inputs for the scalar bridge: scalar first, array second. */
+function scalarFirst(value: string | string[] | undefined): unknown[] {
+  if (value === undefined) return [undefined];
+  if (typeof value === 'string') return [value, [value]];
+  // Repeated keys: `value[0]` matches URLSearchParams.get().
+  //
+  // A raw `[]` carries no value at all. `value[0]` is `undefined`, which is
+  // the shape the scalar bridge has always passed for it, so `undefined`
+  // stays FIRST — an empty array must keep meaning "absent" and land on the
+  // schema's default. Only `defineSearchParams().parse({ tags: [] })`, the
+  // record form, can produce one: URLSearchParams never yields an empty list.
+  return value.length > 0 ? [value[0], value] : [undefined, value];
+}
+
+/** Candidate inputs for the array bridge: array first, scalar second. */
+function arrayFirst(value: string | string[] | undefined): unknown[] {
+  if (value === undefined) return [undefined];
+  if (typeof value === 'string') return [[value], value];
+  // `[]` first here for the same reason, inverted: the array bridge has
+  // always passed the empty array straight through.
+  return value.length > 0 ? [value, value[0]] : [value, undefined];
+}
+
+/**
+ * Validate `value` against `schema` in each candidate shape, then fall back
+ * to the schema's default. Shared by every bridge — they differ only in
+ * which candidates they offer, and in what order.
+ */
+function parseThroughSchema<T>(
+  schema: StandardSchemaV1<T>,
+  candidates: (value: string | string[] | undefined) => unknown[],
+  value: string | string[] | undefined
+): T {
+  const inputs = candidates(value);
+  for (let i = 0; i < inputs.length; i++) {
+    // A throw from the FIRST candidate propagates, unchanged: that is the
+    // shape the schema was written against, and a throw from it is the
+    // deliberate signal design/23 protects — an app schema may `redirect()`
+    // or `notFound()` on a value it refuses, and `validateSync` throws on
+    // an async schema.
+    //
+    // A throw from a LATER candidate is ours, not the app's. We invented
+    // that shape; the schema never agreed to receive it. A scalar-only
+    // hand-written validator doing `value.toUpperCase()`, or a schema that
+    // is async for the array shape only, would turn a field that used to
+    // fall back to its default into a render-phase 500. Treat it as "this
+    // shape does not fit" and keep going.
+    let result: StandardSchemaResult<T>;
+    try {
+      result = validateSync(schema, inputs[i]);
+    } catch (error) {
+      if (i === 0) throw error;
+      continue;
+    }
+    if (!result.issues) {
+      return result.value;
+    }
+  }
+
+  // No shape validated — try parsing undefined to get the default.
+  // Re-validate each time so factory defaults (e.g. .default(() => []))
+  // produce fresh values.
+  const defaultResult = validateSync(schema, undefined);
+  if (!defaultResult.issues) {
+    return defaultResult.value;
+  }
+
+  // No default available — the field is implicitly optional. Return
+  // undefined; defineSearchParams widens the field's inferred type to
+  // T | undefined via InferField so this doesn't lie.
+  // design/23-search-params.md §"Implicit Optionality"
+  return undefined as T;
+}
+
 /**
  * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
  * Codec<T>.
  *
- * Parse: coerces the raw string through the schema. On validation failure,
- * parses `undefined` to get the schema's default value (the schema should have
- * a `.default()` call). If that also fails, returns `undefined`.
+ * Parse: coerces the raw URL value through the schema, trying the scalar
+ * shape and then the array shape (see `scalarFirst`), so an array schema
+ * works bare: `z.array(z.string()).default([])` yields `[]` when absent,
+ * `['a']` for `?tags=a`, and `['a','b']` for `?tags=a&tags=b`. When no
+ * shape validates, parses `undefined` to get the schema's default (the
+ * schema should have a `.default()` call). If that also fails, returns
+ * `undefined`.
  *
- * Serialize: uses `String()` for primitives, `null` for null/undefined.
+ * Serialize: `String()` for primitives, `null` for null/undefined. Note
+ * that `String(['a','b'])` is `'a,b'` — the same string `fromArraySchema`
+ * writes — so a bare array schema round-trips exactly as design/09
+ * §"Array params" describes.
+ *
+ * This is the SEARCH-PARAM bridge. Cookies use `fromCookieSchema`; a
+ * cookie has no array shape (see below).
  *
  * ```ts
- * import { fromSchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
+ * const tagsCodec = fromSchema(z.array(z.string()).default([]))
  * ```
  */
 export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
-    parse(value: string | string[] | undefined): T {
-      // For array inputs (duplicate query keys), use the first value.
-      // Browsers and URLSearchParams.get() return the first occurrence.
-      const input = Array.isArray(value) ? value[0] : value;
-
-      // Try parsing the raw value
-      const result = validateSync(schema, input);
-      if (!result.issues) {
-        return result.value;
-      }
-
-      // On failure, try parsing undefined to get the default.
-      // Re-validate each time so factory defaults (e.g. .default(() => []))
-      // produce fresh values.
-      const defaultResult = validateSync(schema, undefined);
-      if (!defaultResult.issues) {
-        return defaultResult.value;
+    parse: (value: string | string[] | undefined): T =>
+      parseThroughSchema(schema, scalarFirst, value),
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
       }
-
-      // No default available — the field is implicitly optional. Return
-      // undefined; defineSearchParams widens the field's inferred type to
-      // T | undefined via InferField so this doesn't lie.
-      // design/23-search-params.md §"Implicit Optionality"
-      return undefined as T;
+      return String(value);
     },
+  };
+}
 
+// ---------------------------------------------------------------------------
+// fromCookieSchema — bridge for cookie values
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a Standard Schema for a COOKIE value.
+ *
+ * Identical to `fromSchema` minus the array shape, because a cookie cannot
+ * carry one: `Cookie:` headers and `document.cookie` yield a single string
+ * per name, and there is no repeated-key concept to be tolerant of. Sharing
+ * the search-param bridge here meant a cookie written by this very codec —
+ * `serialize(['a','b'])` → `a,b` — read back as the one-element array
+ * `['a,b']` instead of failing to its default: no repeated key in sight,
+ * just a delimiter reinterpreted as data.
+ *
+ * The `serialize` contract also differs by domain and must not be unified:
+ * for a search param `null` means "omit the key", for a cookie it means
+ * **delete the cookie** (design/29-cookies.md).
+ */
+export function fromCookieSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse: (value: string | string[] | undefined): T =>
+      parseThroughSchema(schema, scalarOnly, value),
     serialize(value: T): string | null {
       if (value === null || value === undefined) {
         return null;
@@ -214,32 +344,24 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
  *
  * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
  * ```
+ *
+ * Since TIM-1352 a bare array schema works through `fromSchema` too, so
+ * this is no longer required to make an array field parse. Two cases still
+ * want it, both listed in design/23 §"Shape tolerance":
+ *
+ * 1. A **permissive** schema meant as an array — one that accepts a string
+ *    as readily as an array (`z.any()`, a hand-written coercing validator)
+ *    — where scalar-first ordering would settle on the scalar shape.
+ * 2. An array schema wrapped in `.catch([])`, which swallows the failure
+ *    that would otherwise trigger the array attempt.
+ *
+ * It also serializes an empty array to `null` (omitting the key) where
+ * `fromSchema` writes `''`.
  */
 export function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
-    parse(value: string | string[] | undefined): T {
-      // Coerce single string to array for array schemas
-      let input: unknown = value;
-      if (typeof value === 'string') {
-        input = [value];
-      } else if (value === undefined) {
-        input = undefined;
-      }
-
-      const result = validateSync(schema, input);
-      if (!result.issues) {
-        return result.value;
-      }
-
-      // On failure, try undefined for default
-      const defaultResult = validateSync(schema, undefined);
-      if (!defaultResult.issues) {
-        return defaultResult.value;
-      }
-
-      return undefined as T;
-    },
-
+    parse: (value: string | string[] | undefined): T =>
+      parseThroughSchema(schema, arrayFirst, value),
     serialize(value: T): string | null {
       if (value === null || value === undefined) {
         return null;