@confect/core 10.0.0-next.21 → 10.0.0-next.23

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@confect/core",
   "description": "Shared specs and schemas used by all Confect packages",
-  "version": "10.0.0-next.21",
+  "version": "10.0.0-next.23",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.115",
     "@types/node": "24.13.3",
     "confect-bench-harness": "0.0.0",
-    "effect": "4.0.0-rc.112",
-    "tsdown": "0.22.14",
+    "effect": "4.0.0-rc.115",
+    "tsdown": "0.23.0",
     "tsx": "4.23.13",
     "typescript": "7.0.2",
     "unrun": "0.3.1",
-    "vitest": "4.1.11"
+    "vitest": "5.0.0"
   },
   "engines": {
     "node": ">=24"
@@ -51,7 +51,7 @@
   "module": "./dist/index.js",
   "peerDependencies": {
     "convex": "^1.32.0",
-    "effect": "^4.0.0-rc.112"
+    "effect": "^4.0.0-rc.115"
   },
   "repository": {
     "type": "git",
@@ -65,6 +65,7 @@
     "clean": "shx rm -rf dist coverage node_modules",
     "dev": "tsdown --watch --no-clean --config-loader unrun",
     "test": "vitest run",
-    "typecheck": "tsc -b tsconfig.src.json"
+    "typecheck": "tsc -b tsconfig.src.json",
+    "typecheck:inexact": "tsc --noEmit --project tsconfig.json --exactOptionalPropertyTypes false"
   }
 }

package/src/FunctionProvenance.ts

@@ -27,7 +27,9 @@ export interface ArgsSchema<
   readonly fields: ArgsFields_;
 }
 
-/** Erased structural view used after the exact field map is no longer needed. */
+/**
+ * Erased structural view used after the exact field map is no longer needed.
+ */
 export type AnyArgsSchema = ArgsSchema<ArgsFields>;
 
 export type FunctionProvenance = Data.TaggedEnum<{
@@ -44,12 +46,11 @@ export type FunctionProvenance = Data.TaggedEnum<{
 }>;
 
 /**
- * The declaration shape of a Confect function — orthogonal to both the
- * provenance origin (Confect vs Convex) and the function type
- * (query/mutation/action). A `Standard` function declares its args fields and
- * returns schema directly; a `Paginated` function declares user-args fields
- * and an item schema from which the Convex-facing `args`/`returns` are
- * composed.
+ * The declaration shape of a Confect function—orthogonal to both the provenance
+ * origin (Confect vs Convex) and the function type (query/mutation/action). A
+ * `Standard` function declares its args fields and returns schema directly; a
+ * `Paginated` function declares user-args fields and an item schema from which
+ * the Convex-facing `args`/`returns` are composed.
  */
 export type ConfectKind = Standard | Paginated;
 
@@ -62,11 +63,17 @@ export interface Paginated<
   Item extends Schema.Codec<any, any> = Schema.Codec<any, any>,
 > {
   readonly _tag: "Paginated";
-  /** User-declared args — no `paginationOpts`. */
+  /**
+   * User-declared args—no `paginationOpts`.
+   */
   readonly userArgs: ArgsSchema<UserArgsFields_>;
-  /** Page element schema. */
+  /**
+   * Page element schema.
+   */
   readonly item: Item;
-  /** Mutable array of items — the page decode target. */
+  /**
+   * Mutable array of items—the page decode target.
+   */
   readonly page: Schema.Codec<any, any>;
 }
 
@@ -105,19 +112,20 @@ export const FunctionProvenance = Data.taggedEnum<FunctionProvenance>();
 const Standard: Standard = { _tag: "Standard" };
 
 /**
- * Build a `Confect` provenance from lazy args-fields and schema thunks.
- * `args`, `returns`, and `error` are exposed as sync lazy memoised getters
- * (via {@link Lazy.defineProperty}) that only evaluate their thunk on first
- * access, mirroring how `Table` defers `Fields`/`Doc`. This keeps importing the
- * assembled `_generated/spec.ts` cheap — no `Schema.Struct(...)` /
- * `Schema.Array(...)` work runs at module load; it is deferred to the first
- * invocation that actually compiles validators or runs a codec.
+ * Build a `Confect` provenance from lazy args-fields and schema thunks. `args`,
+ * `returns`, and `error` are exposed as sync lazy memoised getters (via
+ * {@link Lazy.defineProperty}) that only evaluate their thunk on first access,
+ * mirroring how `Table` defers `Fields`/`Doc`. This keeps importing the
+ * assembled `_generated/spec.ts` cheap—no
+ * `Schema.Struct(...)`/`Schema.Array(...)` work runs at module load; it is
+ * deferred to the first invocation that actually compiles validators or runs a
+ * codec.
  *
  * The object is built by hand rather than through `FunctionProvenance.Confect`
  * because the `Data` constructor copies its input with `Object.assign`, which
- * would force the getters at construction time and defeat the laziness.
- * `error` is only installed when an `errorThunk` is provided, so its absence
- * is observable via `"error" in provenance` without forcing anything; nothing
+ * would force the getters at construction time and defeat the laziness. `error`
+ * is only installed when an `errorThunk` is provided, so its absence is
+ * observable via `"error" in provenance` without forcing anything; nothing
  * relies on `Data`'s structural `Equal`/`Hash` for provenance values.
  */
 export const Confect = <
@@ -141,8 +149,8 @@ export const Confect = <
 };
 
 /**
- * The composed args schema of a paginated query: the user-declared fields
- * plus the `paginationOpts` field managed by Convex's pagination protocol.
+ * The composed args schema of a paginated query: the user-declared fields plus
+ * the `paginationOpts` field managed by Convex's pagination protocol.
  *
  * The fields-first representation keeps the user-declared map available for
  * type-level composition without reconstructing it from an erased schema.
@@ -157,8 +165,8 @@ export type PaginatedArgs<UserArgsFields extends ArgsFields> = Schema.Struct<
 >;
 
 /**
- * The composed returns schema of a paginated query: a `PaginationResult` of
- * the item schema. Same deferred-conditional device as {@link PaginatedArgs}.
+ * The composed returns schema of a paginated query: a `PaginationResult` of the
+ * item schema. Same deferred-conditional device as {@link PaginatedArgs}.
  */
 export type PaginatedReturns<Item extends Schema.Codec<any, any>> =
   PaginationResult.PaginationResult<Item> extends infer ComposedReturns extends
@@ -183,8 +191,8 @@ export interface AnyConfectPaginated extends AnyConfect {
 
 /**
  * Build the provenance of a paginated query from lazy schema thunks, with the
- * same laziness contract as {@link Confect}. The user-facing schemas live on
- * the `Paginated` kind (`kind.userArgs`, `kind.item`, `kind.page`) — the kind
+ * same laziness contract as {@link Confect}. The user-facing schemas live on the
+ * `Paginated` kind (`kind.userArgs`, `kind.item`, `kind.page`)—the kind
  * container is built eagerly (it is cheap) while the schemas inside it stay
  * lazy. The composed Convex-facing `args`/`returns` are derived lazily from
  * them: `args` spreads the user fields plus `paginationOpts`, and `returns`
@@ -216,7 +224,7 @@ export const ConfectPaginated = <
     const fields = paginatedKind.userArgs.fields;
     if ("paginationOpts" in fields) {
       throw new globalThis.Error(
-        "A paginated query's args schema must not declare `paginationOpts` — " +
+        "A paginated query's args schema must not declare `paginationOpts`—" +
           "it is added automatically from the `PaginationOptions` schema",
       );
     }

package/src/FunctionSpec.ts

@@ -1,3 +1,4 @@
+import type * as MiddlewareAttachment from "./MiddlewareAttachment";
 import type {
   DefaultFunctionArgs,
   FunctionType,
@@ -32,6 +33,9 @@ export interface FunctionSpec<
   readonly name: Name_;
   readonly functionProvenance: FunctionProvenance_;
   readonly middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
+  readonly middlewareAttachments: ReadonlyArray<
+    MiddlewareAttachment.MiddlewareAttachment<MiddlewareSpecs_>
+  >;
 }
 
 export interface Builder<
@@ -55,6 +59,7 @@ export interface Builder<
         FunctionProvenance_,
         MiddlewareSpecs_
       >,
+    ...options: MiddlewareAttachment.Args<NoInfer<MiddlewareSpec_>>
   ): Builder<
     RuntimeAndFunctionType_,
     FunctionVisibility_,
@@ -136,7 +141,9 @@ export type Name<FunctionSpec_ extends AnyWithProps> = FunctionSpec_["name"];
 export type MiddlewareSpecs<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_["middlewareSpecs"][number];
 
-/** The field map declared by a Confect-provenance spec. */
+/**
+ * The field map declared by a Confect-provenance spec.
+ */
 export type ArgsFields<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_ extends {
     readonly functionProvenance: {
@@ -152,7 +159,9 @@ export type ArgsFields<FunctionSpec_ extends AnyWithProps> =
       ? FunctionProvenance.ArgsFields
       : never;
 
-/** The args schema assembled from a Confect-provenance spec's field map. */
+/**
+ * The args schema assembled from a Confect-provenance spec's field map.
+ */
 export type ArgsSchema<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_ extends {
     readonly functionProvenance: {
@@ -186,10 +195,10 @@ export type ErrorSchema<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_ extends {
     readonly functionProvenance: {
       readonly _tag: "Confect";
-      readonly error?: infer ErrorSchema_ extends Schema.Codec<any, any>;
+      readonly error?: infer ErrorSchema_;
     };
   }
-    ? ErrorSchema_
+    ? Extract<ErrorSchema_, Schema.Codec<any, any>>
     : never;
 
 export type Args<FunctionSpec_ extends AnyWithProps> = FunctionSpec_ extends {
@@ -282,9 +291,14 @@ export type WithoutName<
 const Proto = {
   [TypeId]: TypeId,
 
+  get middlewareSpecs() {
+    return this.middlewareAttachments.map(({ spec }) => spec);
+  },
+
   middleware(
     this: AnyWithProps,
     middlewareSpec: MiddlewareSpec.AnyMiddlewareSpec,
+    ...options: ReadonlyArray<unknown>
   ) {
     if (this.functionProvenance._tag === "Convex") {
       throw new Error(
@@ -298,8 +312,9 @@ const Proto = {
       );
     }
     if (
-      this.middlewareSpecs.some(
-        (existing) => existing.key === middlewareSpec.key,
+      !("options" in middlewareSpec) &&
+      this.middlewareAttachments.some(
+        ({ spec }) => spec.key === middlewareSpec.key,
       )
     ) {
       throw new Error(
@@ -312,10 +327,13 @@ const Proto = {
       functionVisibility: this.functionVisibility,
       name: this.name,
       functionProvenance: this.functionProvenance,
-      middlewareSpecs: [...this.middlewareSpecs, middlewareSpec],
+      middlewareAttachments: [
+        ...this.middlewareAttachments,
+        { spec: middlewareSpec, options: options[0] },
+      ],
     });
   },
-};
+} satisfies ThisType<AnyWithProps>;
 
 interface Options {
   readonly name: string;
@@ -373,7 +391,7 @@ const make = <
         args === undefined
           ? FunctionProvenance.Confect(() => ({}), returns, error)
           : FunctionProvenance.Confect(args, returns, error),
-      middlewareSpecs: [],
+      middlewareAttachments: [],
     });
   }
 
@@ -381,10 +399,10 @@ const make = <
 };
 
 /**
- * `Schema.Struct` fields that must not declare `paginationOpts`. Used to
- * reject a user args schema that redeclares the field the paginated
- * constructors add themselves; the check reports at the `args` thunk with an
- * unsatisfiable type when violated.
+ * `Schema.Struct` fields that must not declare `paginationOpts`. Used to reject
+ * a user args schema that redeclares the field the paginated constructors add
+ * themselves; the check reports at the `args` thunk with an unsatisfiable type
+ * when violated.
  */
 type ForbidPaginationOpts<
   UserArgsFields extends FunctionProvenance.ArgsFields,
@@ -448,7 +466,7 @@ const makePaginated = <
         args === undefined
           ? FunctionProvenance.ConfectPaginated(() => ({}), item, error)
           : FunctionProvenance.ConfectPaginated(args, item, error),
-      middlewareSpecs: [],
+      middlewareAttachments: [],
     });
   }
 
@@ -562,7 +580,7 @@ const makeConvex =
         ExtractArgs<F>,
         ExtractReturns<F>
       >(),
-      middlewareSpecs: [],
+      middlewareAttachments: [],
     }) as any;
   };
 

package/src/GroupPath.ts

@@ -4,7 +4,8 @@ import type * as GroupSpec from "./GroupSpec";
  * Recursively generates paths for a group and its nested groups.
  *
  * - For a group with no subgroups, returns just the group name.
- * - For a group with subgroups, returns the group name plus all possible paths through its direct subgroups.
+ * - For a group with subgroups, returns the group name plus all possible paths
+ *   through its direct subgroups.
  */
 export type All<
   Group extends GroupSpec.AnyWithProps,
@@ -26,13 +27,11 @@ type AllHelper<
   : never;
 
 /**
- * Recursively extracts the group at the given dot-separated path.
- * Path must match the format defined in `Path` above, e.g. "group" or "group.subgroup".
+ * Recursively extracts the group at the given dot-separated path. Path must
+ * match the format defined in `Path` above, e.g. "group" or "group.subgroup".
  *
  * @example
- * ```ts
- * type G = WithPath<RootGroup, "group.subgroup">;
- * ```
+ *   type G = WithPath<RootGroup, "group.subgroup">;
  */
 export type GroupAt<
   Group,

package/src/GroupSpec.ts

@@ -1,5 +1,7 @@
+import * as MiddlewareAttachment from "./MiddlewareAttachment";
 import * as Predicate from "effect/Predicate";
 import * as Record from "effect/Record";
+import * as Result from "effect/Result";
 import type * as FunctionSpec from "./FunctionSpec";
 import type * as MiddlewareSpec from "./MiddlewareSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
@@ -18,7 +20,7 @@ export interface GroupSpec<
   // Subgroups may be of any runtime, independent of this group's own runtime: a
   // group is only a namespace for its children, which are otherwise-independent
   // modules. Functions, by contrast, stay homogeneous (a Node group only accepts
-  // Node actions) — `addFunction` keeps the `<Runtime>` bound below.
+  // Node actions)—`addFunction` keeps the `<Runtime>` bound below.
   Groups_ extends AnyWithProps = never,
   MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec = never,
 > {
@@ -36,6 +38,9 @@ export interface GroupSpec<
     [GroupName in Name<Groups_>]: WithName<Groups_, GroupName>;
   };
   readonly middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
+  readonly middlewareAttachments: ReadonlyArray<
+    MiddlewareAttachment.MiddlewareAttachment<MiddlewareSpecs_>
+  >;
   readonly "~Functions": Functions_;
   readonly "~Groups": Groups_;
 
@@ -72,6 +77,7 @@ export interface GroupSpec<
         Functions_,
         MiddlewareSpecs_
       >,
+    ...options: MiddlewareAttachment.Args<NoInfer<MiddlewareSpec_>>
   ): GroupSpec<
     Runtime,
     Name_,
@@ -123,7 +129,10 @@ export type WithName<
   Name_ extends Name<Group>,
 > = Extract<Group, { readonly name: Name_ }>;
 
-/** Assigns a segment name to a leaf group created with {@link make} for typing and refs. */
+/**
+ * Assigns a segment name to a leaf group created with {@link make} for typing
+ * and refs.
+ */
 export type NamedAt<Group extends Any, Name_ extends string> = Omit<
   Group,
   "name"
@@ -154,22 +163,27 @@ export type AddGroups<
 const Proto = {
   [TypeId]: TypeId,
 
+  get middlewareSpecs() {
+    return this.middlewareAttachments.map(({ spec }) => spec);
+  },
+
   addFunction<Function extends FunctionSpec.AnyWithProps>(
     this: Any,
     function_: Function,
   ) {
     const this_ = this as AnyWithProps;
 
-    const overlapping = function_.middlewareSpecs.find(
-      (functionMiddlewareSpec) =>
-        this_.middlewareSpecs.some(
-          (groupMiddlewareSpec) =>
+    const overlapping = function_.middlewareAttachments.find(
+      ({ spec: functionMiddlewareSpec }) =>
+        !("options" in functionMiddlewareSpec) &&
+        this_.middlewareAttachments.some(
+          ({ spec: groupMiddlewareSpec }) =>
             groupMiddlewareSpec.key === functionMiddlewareSpec.key,
         ),
     );
     if (overlapping !== undefined) {
       throw new Error(
-        `Middleware "${overlapping.key}" is attached to both function "${function_.name}" and its group`,
+        `Middleware "${overlapping.spec.key}" is attached to both function "${function_.name}" and its group`,
       );
     }
 
@@ -178,7 +192,7 @@ const Proto = {
       name: this_.name,
       functions: Record.set(this_.functions, function_.name, function_),
       groups: this_.groups,
-      middlewareSpecs: this_.middlewareSpecs,
+      middlewareAttachments: this_.middlewareAttachments,
     });
   },
 
@@ -191,7 +205,7 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: Record.set(this_.groups, group_.name, group_),
-      middlewareSpecs: this_.middlewareSpecs,
+      middlewareAttachments: this_.middlewareAttachments,
     });
   },
 
@@ -204,19 +218,21 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: Record.set(this_.groups, name, withName(name, group_)),
-      middlewareSpecs: this_.middlewareSpecs,
+      middlewareAttachments: this_.middlewareAttachments,
     });
   },
 
   middleware<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec>(
     this: Any,
     middlewareSpec: MiddlewareSpec_,
+    ...options: ReadonlyArray<unknown>
   ) {
     const this_ = this as AnyWithProps;
 
     if (
-      this_.middlewareSpecs.some(
-        (existing) => existing.key === middlewareSpec.key,
+      !("options" in middlewareSpec) &&
+      this_.middlewareAttachments.some(
+        ({ spec }) => spec.key === middlewareSpec.key,
       )
     ) {
       throw new Error(
@@ -226,8 +242,9 @@ const Proto = {
 
     for (const function_ of Object.values(this_.functions)) {
       if (
-        function_.middlewareSpecs.some(
-          (existing) => existing.key === middlewareSpec.key,
+        !("options" in middlewareSpec) &&
+        function_.middlewareAttachments.some(
+          ({ spec }) => spec.key === middlewareSpec.key,
         )
       ) {
         throw new Error(
@@ -241,37 +258,53 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: this_.groups,
-      middlewareSpecs: [...this_.middlewareSpecs, middlewareSpec],
+      middlewareAttachments: [
+        ...this_.middlewareAttachments,
+        { spec: middlewareSpec, options: options[0] },
+      ],
     });
   },
-};
+} satisfies ThisType<AnyWithProps>;
 
 const makeProto = <
   Runtime extends RuntimeAndFunctionType.Runtime,
   Name_ extends string,
   Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>,
   Groups_ extends AnyWithPropsWithRuntime<Runtime>,
-  MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec,
+  MiddlewareAttachments_ extends
+    ReadonlyArray<MiddlewareAttachment.MiddlewareAttachment>,
 >({
   runtime,
   name,
   functions,
   groups,
-  middlewareSpecs,
+  middlewareAttachments,
 }: {
   runtime: Runtime;
   name: Name_;
   functions: Record.ReadonlyRecord<string, Functions_>;
   groups: Record.ReadonlyRecord<string, Groups_>;
-  middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
-}): GroupSpec<Runtime, Name_, Functions_, Groups_, MiddlewareSpecs_> =>
+  middlewareAttachments: MiddlewareAttachments_;
+}): GroupSpec<
+  Runtime,
+  Name_,
+  Functions_,
+  Groups_,
+  MiddlewareAttachments_[number]["spec"]
+> =>
   Object.assign(Object.create(Proto), {
     runtime,
     name,
     functions,
     groups,
-    middlewareSpecs,
-  }) as GroupSpec<Runtime, Name_, Functions_, Groups_, MiddlewareSpecs_>;
+    middlewareAttachments,
+  }) as GroupSpec<
+    Runtime,
+    Name_,
+    Functions_,
+    Groups_,
+    MiddlewareAttachments_[number]["spec"]
+  >;
 
 export const make = (): GroupSpec<"Convex", ""> =>
   makeProto({
@@ -279,7 +312,7 @@ export const make = (): GroupSpec<"Convex", ""> =>
     name: "",
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 
 export const makeAt = <const Name_ extends string>(
@@ -292,7 +325,7 @@ export const makeAt = <const Name_ extends string>(
     name,
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 };
 
@@ -302,7 +335,7 @@ export const makeNode = (): GroupSpec<"Node", ""> =>
     name: "",
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 
 export const makeNodeAt = <const Name_ extends string>(
@@ -315,14 +348,15 @@ export const makeNodeAt = <const Name_ extends string>(
     name,
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 };
 
-export const withName = <const Name_ extends string>(
+export function withName<const Name_ extends string, Group extends Any>(
   name: Name_,
-  group: Any,
-): AnyWithProps => {
+  group: Group,
+): NamedAt<Group, Name_>;
+export function withName(name: string, group: Any): AnyWithProps {
   validateConfectFunctionIdentifier(name);
   const group_ = group as AnyWithProps;
 
@@ -335,6 +369,24 @@ export const withName = <const Name_ extends string>(
     name,
     functions: group_.functions,
     groups: group_.groups,
-    middlewareSpecs: group_.middlewareSpecs,
+    middlewareAttachments: group_.middlewareAttachments,
+  });
+}
+
+export const validateMiddleware = (
+  group: AnyWithProps,
+): Result.Result<void, MiddlewareAttachment.ValidationError> =>
+  Result.gen(function* () {
+    yield* MiddlewareAttachment.validateAll(
+      group.middlewareAttachments,
+      `group "${group.name}"`,
+    );
+    for (const function_ of Object.values(group.functions)) {
+      yield* MiddlewareAttachment.validateAll(
+        [...group.middlewareAttachments, ...function_.middlewareAttachments],
+        `function "${function_.name}"`,
+      );
+    }
+    for (const child of Object.values(group.groups))
+      yield* validateMiddleware(child);
   });
-};

package/src/Identifier.ts

@@ -95,15 +95,16 @@ export const validateConfectFunctionIdentifier = (identifier: string) => {
 };
 
 /**
- * Validate that `identifier` is suitable as a Convex table name (and, equivalently,
- * as a `confect/tables/<identifier>.ts` filename).
+ * Validate that `identifier` is suitable as a Convex table name (and,
+ * equivalently, as a `confect/tables/<identifier>.ts` filename).
  *
  * Rules:
- * - Must match `/^[A-Za-z][A-Za-z0-9_]*$/` — letter-leading, alphanumeric plus
+ *
+ * - Must match `/^[A-Za-z][A-Za-z0-9_]*$/`—letter-leading, alphanumeric plus
  *   underscore. No `$` (not a valid Convex table name character); no leading
  *   `_` (Convex reserves `_<name>` for its system tables).
- * - Must not be a reserved JavaScript identifier, so the name can also be used
- *   as a binding name in generated code without escaping.
+ * - Must not be a reserved JavaScript identifier, so the name can also be used as
+ *   a binding name in generated code without escaping.
  */
 export const validateConfectTableIdentifier = (identifier: string) => {
   if (!matchesTableNamePattern(identifier)) {

package/src/Lazy.ts

@@ -1,21 +1,19 @@
 /**
  * Install a lazy memoised property on `target`. The first access runs
- * `compute()` and replaces the getter with a plain, non-writable data
- * property whose value is the computed result. Subsequent accesses hit
- * the V8 fast path for own data properties — no function call, identical
- * returned reference — so first and second-and-subsequent accesses are
- * observably indistinguishable.
+ * `compute()` and replaces the getter with a plain, non-writable data property
+ * whose value is the computed result. Subsequent accesses hit the V8 fast path
+ * for own data properties—no function call, identical returned reference—so
+ * first and second-and-subsequent accesses are observably indistinguishable.
  *
- * The replacement property is `enumerable: true` so the lazy property
- * still participates in `Object.keys` / `JSON.stringify` after it
- * materialises, matching the shape of a plain data property. The property
- * is also `enumerable` before materialising, so presence checks
- * (`"key" in target`, `Object.hasOwn(target, key)`) observe it without
- * forcing the computation.
+ * The replacement property is `enumerable: true` so the lazy property still
+ * participates in `Object.keys`/`JSON.stringify` after it materialises,
+ * matching the shape of a plain data property. The property is also
+ * `enumerable` before materialising, so presence checks (`"key" in target`,
+ * `Object.hasOwn(target, key)`) observe it without forcing the computation.
  *
  * This is the single shared implementation consumed across packages (e.g.
- * `@confect/core`'s lazy `FunctionSpec` schemas and lazy `Table` `Fields` /
- * `Doc`), so there is no chance of the two drifting apart.
+ * `@confect/core`'s lazy `FunctionSpec` schemas and lazy `Table`
+ * `Fields`/`Doc`), so there is no chance of the two drifting apart.
  */
 export const defineProperty = <T extends object, K extends PropertyKey>(
   target: T,