@confect/core 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @confect/core
 
+## 10.1.0
+
+### Patch Changes
+
+- 89daa88: Fix `Table.Doc` to enforce checks attached to table structs and unions when decoding and encoding documents, and preserve a union's `oneOf` mode.
+
 ## 10.0.0
 
 ### Major Changes

package/dist/SystemFields.d.ts

@@ -17,15 +17,15 @@ type SystemFieldsFor<TableName extends string> = ReturnType<typeof SystemFields<
 /**
  * Extend a table schema with Convex system fields.
  *
- * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union` has
- * them distributed across its members, preserving the schema's `Struct`/`Union`
- * structure. Any other object-shaped schema—one built with
- * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended
- * schema—is extended at the AST level: every object node in its encoding chain
- * gains the system fields, and each transformation is wrapped so the fields
- * bypass the user-defined getters. Schemas that do not resolve to an object
- * shape at every step (such as `Schema.Class`, whose decoded values are class
- * instances) are rejected with a descriptive error.
+ * A plain `Struct` gains the fields via `mapFields` and a `Union` has them
+ * distributed across its members via `mapMembers`, preserving the schema's
+ * checks and `Struct`/`Union` structure. Any other object-shaped schema—one
+ * built with `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a
+ * suspended schema—is extended at the AST level: every object node in its
+ * encoding chain gains the system fields, and each transformation is wrapped so
+ * the fields bypass the user-defined getters. Schemas that do not resolve to an
+ * object shape at every step (such as `Schema.Class`, whose decoded values are
+ * class instances) are rejected with a descriptive error.
  *
  * Note that struct-level checks on an extended schema observe the value with
  * the system fields attached, and encoding an extended schema emits the system

package/dist/SystemFields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SystemFields.d.ts","sourceRoot":"","sources":["../src/SystemFields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAOhF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,SAAS,MAAM,aAAa,SAAS;;;EAIvE,CAAC;AAEL;;;GAGG;AACH,KAAK,eAAe,CAAC,SAAS,SAAS,MAAM,IAAI,UAAU,CACzD,OAAO,YAAY,CAAC,SAAS,CAAC,CAC/B,CAAC,QAAQ,CAAC,CAAC;AA0HZ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,SAAS,MAAM,EACxB,WAAW,SAAS,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,aAE/B,SAAS,UACZ,WAAW,KAClB,sBAAsB,CAAC,SAAS,EAAE,WAAW,CA0C/C,CAAC;AAEF;;;;GAIG;AACH,KAAK,iBAAiB,CAAC,SAAS,SAAS,MAAM,EAAE,CAAC,IAChD,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAC9D,MAAM,CAAC,MAAM,CACX,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CACnE,GACD,CAAC,SAAS,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,MAAM,OAAO,CAAC,GAC/C,MAAM,CAAC,KAAK,CACV,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,EACjC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CACrC,GACD,KAAK,CAAC;AAEd;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,CAChC,SAAS,SAAS,MAAM,EACxB,WAAW,SAAS,MAAM,CAAC,GAAG,IAE9B,WAAW,SAAS,MAAM,CAAC,KAAK,CAC9B,MAAM,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAChD,GACG,MAAM,CAAC,KAAK,CACV,MAAM,CAAC,QAAQ,CACb,QAAQ,CAAC;KACN,CAAC,IAAI,MAAM,OAAO,GAAG,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACpE,CAAC,CACH,CACF,GACD,iBAAiB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAC1B,SAAS,SAAS,MAAM,EACxB,QAAQ,IACN,QAAQ,SAAS,OAAO,GACxB,OAAO,CAAC,SAAS,CAAC,GAAG,iBAAiB,GAAG,QAAQ,GACjD,KAAK,CAAC"}
+{"version":3,"file":"SystemFields.d.ts","sourceRoot":"","sources":["../src/SystemFields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAOhF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,SAAS,MAAM,aAAa,SAAS;;;EAIvE,CAAC;AAEL;;;GAGG;AACH,KAAK,eAAe,CAAC,SAAS,SAAS,MAAM,IAAI,UAAU,CACzD,OAAO,YAAY,CAAC,SAAS,CAAC,CAC/B,CAAC,QAAQ,CAAC,CAAC;AA0HZ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,SAAS,MAAM,EACxB,WAAW,SAAS,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,aAE/B,SAAS,UACZ,WAAW,KAClB,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAyC/C,CAAC;AAEF;;;;GAIG;AACH,KAAK,iBAAiB,CAAC,SAAS,SAAS,MAAM,EAAE,CAAC,IAChD,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAC9D,MAAM,CAAC,MAAM,CACX,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CACnE,GACD,CAAC,SAAS,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,MAAM,OAAO,CAAC,GAC/C,MAAM,CAAC,KAAK,CACV,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,EACjC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CACrC,GACD,KAAK,CAAC;AAEd;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,CAChC,SAAS,SAAS,MAAM,EACxB,WAAW,SAAS,MAAM,CAAC,GAAG,IAE9B,WAAW,SAAS,MAAM,CAAC,KAAK,CAC9B,MAAM,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAChD,GACG,MAAM,CAAC,KAAK,CACV,MAAM,CAAC,QAAQ,CACb,QAAQ,CAAC;KACN,CAAC,IAAI,MAAM,OAAO,GAAG,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACpE,CAAC,CACH,CACF,GACD,iBAAiB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAC1B,SAAS,SAAS,MAAM,EACxB,QAAQ,IACN,QAAQ,SAAS,OAAO,GACxB,OAAO,CAAC,SAAS,CAAC,GAAG,iBAAiB,GAAG,QAAQ,GACjD,KAAK,CAAC"}

package/dist/SystemFields.js

@@ -71,15 +71,15 @@ const makeExtendAst = (systemPropertySignatures) => {
 /**
 * Extend a table schema with Convex system fields.
 *
-* A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union` has
-* them distributed across its members, preserving the schema's `Struct`/`Union`
-* structure. Any other object-shaped schema—one built with
-* `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended
-* schema—is extended at the AST level: every object node in its encoding chain
-* gains the system fields, and each transformation is wrapped so the fields
-* bypass the user-defined getters. Schemas that do not resolve to an object
-* shape at every step (such as `Schema.Class`, whose decoded values are class
-* instances) are rejected with a descriptive error.
+* A plain `Struct` gains the fields via `mapFields` and a `Union` has them
+* distributed across its members via `mapMembers`, preserving the schema's
+* checks and `Struct`/`Union` structure. Any other object-shaped schema—one
+* built with `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a
+* suspended schema—is extended at the AST level: every object node in its
+* encoding chain gains the system fields, and each transformation is wrapped so
+* the fields bypass the user-defined getters. Schemas that do not resolve to an
+* object shape at every step (such as `Schema.Class`, whose decoded values are
+* class instances) are rejected with a descriptive error.
 *
 * Note that struct-level checks on an extended schema observe the value with
 * the system fields attached, and encoding an extended schema emits the system
@@ -89,8 +89,8 @@ const extendWithSystemFields = (tableName, schema) => {
 	const system = SystemFields(tableName).fields;
 	const extendAst = makeExtendAst(pipe(system, Record.toEntries, Array.map(([name, field]) => new SchemaAST.PropertySignature(name, field.ast))));
 	const extend = (s) => {
-		if (s.ast.encoding === void 0 && SchemaAST.isUnion(s.ast) && Array.isArray(s.members)) return Schema.Union(Array.map(s.members, extend));
-		if (s.ast.encoding === void 0 && SchemaAST.isObjects(s.ast) && typeof s.mapFields === "function") return Schema.fieldsAssign(system)(s);
+		if (s.ast.encoding === void 0 && SchemaAST.isUnion(s.ast) && Array.isArray(s.members)) return s.mapMembers(Array.map(extend), { unsafePreserveChecks: true });
+		if (s.ast.encoding === void 0 && SchemaAST.isObjects(s.ast) && typeof s.mapFields === "function") return s.mapFields(Struct.assign(system), { unsafePreserveChecks: true });
 		return Schema.make(extendAst(s.ast));
 	};
 	return extend(schema);

package/dist/SystemFields.js.map

@@ -1 +1 @@
-{"version":3,"file":"SystemFields.js","names":["GenericId.GenericId"],"sources":["../src/SystemFields.ts"],"sourcesContent":["import type { IdField, SystemFields as NonIdSystemFields } from \"convex/server\";\nimport { pipe } from \"effect/Function\";\nimport * as Array from \"effect/Array\";\nimport * as Effect from \"effect/Effect\";\nimport * as Option from \"effect/Option\";\nimport * as Predicate from \"effect/Predicate\";\nimport * as Record from \"effect/Record\";\nimport * as Schema from \"effect/Schema\";\nimport * as SchemaAST from \"effect/SchemaAST\";\nimport * as SchemaGetter from \"effect/SchemaGetter\";\nimport * as SchemaTransformation from \"effect/SchemaTransformation\";\nimport * as Struct from \"effect/Struct\";\nimport * as GenericId from \"./GenericId\";\n\n/**\n * Produces a schema for Convex system fields. In Confect, system fields include\n * `_id`.\n */\nexport const SystemFields = <TableName extends string>(tableName: TableName) =>\n  Schema.Struct({\n    _id: GenericId.GenericId(tableName),\n    _creationTime: Schema.Finite,\n  });\n\n/**\n * The field map added to a table schema, derived from {@link SystemFields} so it\n * stays in lockstep with the runtime schema.\n */\ntype SystemFieldsFor<TableName extends string> = ReturnType<\n  typeof SystemFields<TableName>\n>[\"fields\"];\n\n/**\n * The system field names, derived from {@link SystemFields} so they stay in\n * lockstep with the schema.\n */\nconst systemFieldNames: ReadonlyArray<string> = Record.keys(\n  SystemFields(\"\").fields,\n);\n\nconst isSystemFieldKey = (key: string | symbol): key is string =>\n  Predicate.isString(key) && Array.contains(systemFieldNames, key);\n\nconst splitSystemFields = (input: { [key: PropertyKey]: unknown }) => {\n  const keys = Reflect.ownKeys(input);\n  const pick = (pickedKeys: ReadonlyArray<string | symbol>) =>\n    Record.fromEntries(\n      Array.map(pickedKeys, (key) => [key, input[key]] as const),\n    );\n  return {\n    system: pick(Array.filter(keys, isSystemFieldKey)),\n    rest: pick(Array.filter(keys, Predicate.not(isSystemFieldKey))),\n  };\n};\n\n/**\n * Wraps a transformation getter so the system fields bypass it: they are split\n * off the input before the user-defined getter runs and merged back into its\n * output. Transformations construct fresh objects, so without this the system\n * fields would be dropped at every transformation step.\n */\nconst wrapGetter = <R>(\n  getter: SchemaGetter.Getter<any, any, R>,\n): SchemaGetter.Getter<any, any, R> =>\n  SchemaGetter.transformOptionalEffect((input, options) => {\n    if (Option.isNone(input) || !Predicate.isObject(input.value)) {\n      return SchemaGetter.run(getter, input, options);\n    }\n    const { system, rest } = splitSystemFields(input.value);\n    return SchemaGetter.run(getter, Option.some(rest), options).pipe(\n      Effect.map(\n        Option.map((output) =>\n          Predicate.isObject(output) ? Struct.assign(output, system) : output,\n        ),\n      ),\n    );\n  });\n\nconst wrapTransformation = (\n  transformation: SchemaAST.Link[\"transformation\"],\n): SchemaTransformation.Transformation<any, any, any, any> => {\n  if (!SchemaTransformation.isTransformation(transformation)) {\n    throw new Error(\n      \"Cannot extend a table schema that uses decoding/encoding middleware with system fields\",\n    );\n  }\n  return new SchemaTransformation.Transformation(\n    wrapGetter(transformation.decode),\n    wrapGetter(transformation.encode),\n  );\n};\n\n/**\n * Builds an AST walker that adds the given system-field property signatures to\n * every object node of a schema's AST—including each step of its encoding\n * chain—wrapping transformations so the fields survive them.\n */\nconst makeExtendAst = (\n  systemPropertySignatures: ReadonlyArray<SchemaAST.PropertySignature>,\n) => {\n  const extendEncoding = (encoding: SchemaAST.Encoding): SchemaAST.Encoding =>\n    Array.map(\n      encoding,\n      (link) =>\n        new SchemaAST.Link(\n          extendAst(link.to),\n          wrapTransformation(link.transformation),\n        ),\n    );\n\n  const extendAst = (ast: SchemaAST.AST): SchemaAST.AST => {\n    if (SchemaAST.isUnion(ast)) {\n      return new SchemaAST.Union(\n        Array.map(ast.types, extendAst),\n        ast.options,\n        ast.annotations,\n        ast.checks,\n        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),\n        ast.context,\n        ast.encodingChecks,\n      );\n    }\n    if (SchemaAST.isSuspend(ast)) {\n      return new SchemaAST.Suspend(\n        () => extendAst(ast.thunk()),\n        ast.annotations,\n        undefined,\n        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),\n        ast.context,\n      );\n    }\n    if (SchemaAST.isObjects(ast)) {\n      return new SchemaAST.Objects(\n        Array.appendAll(ast.propertySignatures, systemPropertySignatures),\n        ast.indexSignatures,\n        ast.annotations,\n        ast.checks,\n        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),\n        ast.context,\n        ast.encodingChecks,\n      );\n    }\n    throw new Error(\n      ast._tag === \"Declaration\"\n        ? \"Cannot extend a `Declaration` schema (such as a `Schema.Class`) with system fields: its decoded values are constructed instances, which cannot gain extra fields. Use a plain `Schema.Struct`, or transform to one with `Schema.decodeTo`.\"\n        : `Cannot extend a \\`${ast._tag}\\` schema node with system fields: a table schema must resolve to an object shape at every step of its encoding.`,\n    );\n  };\n\n  return extendAst;\n};\n\n/**\n * Extend a table schema with Convex system fields.\n *\n * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union` has\n * them distributed across its members, preserving the schema's `Struct`/`Union`\n * structure. Any other object-shaped schema—one built with\n * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended\n * schema—is extended at the AST level: every object node in its encoding chain\n * gains the system fields, and each transformation is wrapped so the fields\n * bypass the user-defined getters. Schemas that do not resolve to an object\n * shape at every step (such as `Schema.Class`, whose decoded values are class\n * instances) are rejected with a descriptive error.\n *\n * Note that struct-level checks on an extended schema observe the value with\n * the system fields attached, and encoding an extended schema emits the system\n * fields alongside the table fields.\n */\nexport const extendWithSystemFields = <\n  TableName extends string,\n  TableSchema extends Schema.Codec<any, any>,\n>(\n  tableName: TableName,\n  schema: TableSchema,\n): ExtendWithSystemFields<TableName, TableSchema> => {\n  const system = SystemFields(tableName).fields;\n\n  const extendAst = makeExtendAst(\n    pipe(\n      system,\n      Record.toEntries,\n      Array.map(\n        ([name, field]) => new SchemaAST.PropertySignature(name, field.ast),\n      ),\n    ),\n  );\n\n  const extend = (s: Schema.Top): Schema.Top => {\n    if (\n      s.ast.encoding === undefined &&\n      SchemaAST.isUnion(s.ast) &&\n      Array.isArray((s as { readonly members?: unknown }).members)\n    ) {\n      return Schema.Union(\n        Array.map(\n          (s as Schema.Union<ReadonlyArray<Schema.Top>>).members,\n          extend,\n        ),\n      );\n    }\n    if (\n      s.ast.encoding === undefined &&\n      SchemaAST.isObjects(s.ast) &&\n      typeof (s as { readonly mapFields?: unknown }).mapFields === \"function\"\n    ) {\n      return Schema.fieldsAssign(system)(\n        s as Schema.Struct<Schema.Struct.Fields>,\n      );\n    }\n    return Schema.make(extendAst(s.ast));\n  };\n\n  return extend(schema) as unknown as ExtendWithSystemFields<\n    TableName,\n    TableSchema\n  >;\n};\n\n/**\n * Applies the system fields to a single struct, mirroring\n * `Schema.fieldsAssign`. Any other (already-extended or opaque) schema falls\n * back to a `Codec` carrying the system-field document shape.\n */\ntype ApplySystemFields<TableName extends string, S> =\n  S extends Schema.Struct<infer Fields extends Schema.Struct.Fields>\n    ? Schema.Struct<\n        Struct.Simplify<Struct.Assign<Fields, SystemFieldsFor<TableName>>>\n      >\n    : S extends Schema.Codec<infer Type, infer Encoded>\n      ? Schema.Codec<\n          WithSystemFields<TableName, Type>,\n          WithSystemFields<TableName, Encoded>\n        >\n      : never;\n\n/**\n * Extend a table schema with Convex system fields at the type level.\n *\n * This mirrors the runtime {@link extendWithSystemFields}: a `Struct` gains the\n * system fields directly (matching `Schema.fieldsAssign`), and a `Union` has\n * them distributed across its members (matching\n * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The\n * `Struct`/`Union` structure is preserved rather than collapsed to a bare\n * `Codec`; any other schema falls back to a `Codec` carrying the system-field\n * document shape, matching the runtime's AST-level extension.\n */\nexport type ExtendWithSystemFields<\n  TableName extends string,\n  TableSchema extends Schema.Top,\n> =\n  TableSchema extends Schema.Union<\n    infer Members extends ReadonlyArray<Schema.Top>\n  >\n    ? Schema.Union<\n        Struct.Simplify<\n          Readonly<{\n            [K in keyof Members]: ExtendWithSystemFields<TableName, Members[K]>;\n          }>\n        >\n      >\n    : ApplySystemFields<TableName, TableSchema>;\n\n/**\n * The decoded/encoded document shape: a table's fields plus Convex's system\n * fields. Deliberately a bare intersection (no `Expand`/`Simplify`)—flattening\n * it with a homomorphic mapped type collapses to `{ [x: string]: any }` when\n * `Document` is still an unresolved generic, which breaks structural\n * comparability in the database reader/writer plumbing.\n */\nexport type WithSystemFields<\n  TableName extends string,\n  Document,\n> = Document extends unknown\n  ? IdField<TableName> & NonIdSystemFields & Document\n  : never;\n"],"mappings":"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"}
+{"version":3,"file":"SystemFields.js","names":["GenericId.GenericId"],"sources":["../src/SystemFields.ts"],"sourcesContent":["import type { IdField, SystemFields as NonIdSystemFields } from \"convex/server\";\nimport { pipe } from \"effect/Function\";\nimport * as Array from \"effect/Array\";\nimport * as Effect from \"effect/Effect\";\nimport * as Option from \"effect/Option\";\nimport * as Predicate from \"effect/Predicate\";\nimport * as Record from \"effect/Record\";\nimport * as Schema from \"effect/Schema\";\nimport * as SchemaAST from \"effect/SchemaAST\";\nimport * as SchemaGetter from \"effect/SchemaGetter\";\nimport * as SchemaTransformation from \"effect/SchemaTransformation\";\nimport * as Struct from \"effect/Struct\";\nimport * as GenericId from \"./GenericId\";\n\n/**\n * Produces a schema for Convex system fields. In Confect, system fields include\n * `_id`.\n */\nexport const SystemFields = <TableName extends string>(tableName: TableName) =>\n  Schema.Struct({\n    _id: GenericId.GenericId(tableName),\n    _creationTime: Schema.Finite,\n  });\n\n/**\n * The field map added to a table schema, derived from {@link SystemFields} so it\n * stays in lockstep with the runtime schema.\n */\ntype SystemFieldsFor<TableName extends string> = ReturnType<\n  typeof SystemFields<TableName>\n>[\"fields\"];\n\n/**\n * The system field names, derived from {@link SystemFields} so they stay in\n * lockstep with the schema.\n */\nconst systemFieldNames: ReadonlyArray<string> = Record.keys(\n  SystemFields(\"\").fields,\n);\n\nconst isSystemFieldKey = (key: string | symbol): key is string =>\n  Predicate.isString(key) && Array.contains(systemFieldNames, key);\n\nconst splitSystemFields = (input: { [key: PropertyKey]: unknown }) => {\n  const keys = Reflect.ownKeys(input);\n  const pick = (pickedKeys: ReadonlyArray<string | symbol>) =>\n    Record.fromEntries(\n      Array.map(pickedKeys, (key) => [key, input[key]] as const),\n    );\n  return {\n    system: pick(Array.filter(keys, isSystemFieldKey)),\n    rest: pick(Array.filter(keys, Predicate.not(isSystemFieldKey))),\n  };\n};\n\n/**\n * Wraps a transformation getter so the system fields bypass it: they are split\n * off the input before the user-defined getter runs and merged back into its\n * output. Transformations construct fresh objects, so without this the system\n * fields would be dropped at every transformation step.\n */\nconst wrapGetter = <R>(\n  getter: SchemaGetter.Getter<any, any, R>,\n): SchemaGetter.Getter<any, any, R> =>\n  SchemaGetter.transformOptionalEffect((input, options) => {\n    if (Option.isNone(input) || !Predicate.isObject(input.value)) {\n      return SchemaGetter.run(getter, input, options);\n    }\n    const { system, rest } = splitSystemFields(input.value);\n    return SchemaGetter.run(getter, Option.some(rest), options).pipe(\n      Effect.map(\n        Option.map((output) =>\n          Predicate.isObject(output) ? Struct.assign(output, system) : output,\n        ),\n      ),\n    );\n  });\n\nconst wrapTransformation = (\n  transformation: SchemaAST.Link[\"transformation\"],\n): SchemaTransformation.Transformation<any, any, any, any> => {\n  if (!SchemaTransformation.isTransformation(transformation)) {\n    throw new Error(\n      \"Cannot extend a table schema that uses decoding/encoding middleware with system fields\",\n    );\n  }\n  return new SchemaTransformation.Transformation(\n    wrapGetter(transformation.decode),\n    wrapGetter(transformation.encode),\n  );\n};\n\n/**\n * Builds an AST walker that adds the given system-field property signatures to\n * every object node of a schema's AST—including each step of its encoding\n * chain—wrapping transformations so the fields survive them.\n */\nconst makeExtendAst = (\n  systemPropertySignatures: ReadonlyArray<SchemaAST.PropertySignature>,\n) => {\n  const extendEncoding = (encoding: SchemaAST.Encoding): SchemaAST.Encoding =>\n    Array.map(\n      encoding,\n      (link) =>\n        new SchemaAST.Link(\n          extendAst(link.to),\n          wrapTransformation(link.transformation),\n        ),\n    );\n\n  const extendAst = (ast: SchemaAST.AST): SchemaAST.AST => {\n    if (SchemaAST.isUnion(ast)) {\n      return new SchemaAST.Union(\n        Array.map(ast.types, extendAst),\n        ast.options,\n        ast.annotations,\n        ast.checks,\n        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),\n        ast.context,\n        ast.encodingChecks,\n      );\n    }\n    if (SchemaAST.isSuspend(ast)) {\n      return new SchemaAST.Suspend(\n        () => extendAst(ast.thunk()),\n        ast.annotations,\n        undefined,\n        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),\n        ast.context,\n      );\n    }\n    if (SchemaAST.isObjects(ast)) {\n      return new SchemaAST.Objects(\n        Array.appendAll(ast.propertySignatures, systemPropertySignatures),\n        ast.indexSignatures,\n        ast.annotations,\n        ast.checks,\n        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),\n        ast.context,\n        ast.encodingChecks,\n      );\n    }\n    throw new Error(\n      ast._tag === \"Declaration\"\n        ? \"Cannot extend a `Declaration` schema (such as a `Schema.Class`) with system fields: its decoded values are constructed instances, which cannot gain extra fields. Use a plain `Schema.Struct`, or transform to one with `Schema.decodeTo`.\"\n        : `Cannot extend a \\`${ast._tag}\\` schema node with system fields: a table schema must resolve to an object shape at every step of its encoding.`,\n    );\n  };\n\n  return extendAst;\n};\n\n/**\n * Extend a table schema with Convex system fields.\n *\n * A plain `Struct` gains the fields via `mapFields` and a `Union` has them\n * distributed across its members via `mapMembers`, preserving the schema's\n * checks and `Struct`/`Union` structure. Any other object-shaped schema—one\n * built with `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a\n * suspended schema—is extended at the AST level: every object node in its\n * encoding chain gains the system fields, and each transformation is wrapped so\n * the fields bypass the user-defined getters. Schemas that do not resolve to an\n * object shape at every step (such as `Schema.Class`, whose decoded values are\n * class instances) are rejected with a descriptive error.\n *\n * Note that struct-level checks on an extended schema observe the value with\n * the system fields attached, and encoding an extended schema emits the system\n * fields alongside the table fields.\n */\nexport const extendWithSystemFields = <\n  TableName extends string,\n  TableSchema extends Schema.Codec<any, any>,\n>(\n  tableName: TableName,\n  schema: TableSchema,\n): ExtendWithSystemFields<TableName, TableSchema> => {\n  const system = SystemFields(tableName).fields;\n\n  const extendAst = makeExtendAst(\n    pipe(\n      system,\n      Record.toEntries,\n      Array.map(\n        ([name, field]) => new SchemaAST.PropertySignature(name, field.ast),\n      ),\n    ),\n  );\n\n  const extend = (s: Schema.Top): Schema.Top => {\n    if (\n      s.ast.encoding === undefined &&\n      SchemaAST.isUnion(s.ast) &&\n      Array.isArray((s as { readonly members?: unknown }).members)\n    ) {\n      return (s as Schema.Union<ReadonlyArray<Schema.Top>>).mapMembers(\n        Array.map(extend),\n        { unsafePreserveChecks: true },\n      );\n    }\n    if (\n      s.ast.encoding === undefined &&\n      SchemaAST.isObjects(s.ast) &&\n      typeof (s as { readonly mapFields?: unknown }).mapFields === \"function\"\n    ) {\n      return (s as Schema.Struct<Schema.Struct.Fields>).mapFields(\n        Struct.assign(system),\n        { unsafePreserveChecks: true },\n      );\n    }\n    return Schema.make(extendAst(s.ast));\n  };\n\n  return extend(schema) as unknown as ExtendWithSystemFields<\n    TableName,\n    TableSchema\n  >;\n};\n\n/**\n * Applies the system fields to a single struct, mirroring\n * `Schema.fieldsAssign`. Any other (already-extended or opaque) schema falls\n * back to a `Codec` carrying the system-field document shape.\n */\ntype ApplySystemFields<TableName extends string, S> =\n  S extends Schema.Struct<infer Fields extends Schema.Struct.Fields>\n    ? Schema.Struct<\n        Struct.Simplify<Struct.Assign<Fields, SystemFieldsFor<TableName>>>\n      >\n    : S extends Schema.Codec<infer Type, infer Encoded>\n      ? Schema.Codec<\n          WithSystemFields<TableName, Type>,\n          WithSystemFields<TableName, Encoded>\n        >\n      : never;\n\n/**\n * Extend a table schema with Convex system fields at the type level.\n *\n * This mirrors the runtime {@link extendWithSystemFields}: a `Struct` gains the\n * system fields directly (matching `Schema.fieldsAssign`), and a `Union` has\n * them distributed across its members (matching\n * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The\n * `Struct`/`Union` structure is preserved rather than collapsed to a bare\n * `Codec`; any other schema falls back to a `Codec` carrying the system-field\n * document shape, matching the runtime's AST-level extension.\n */\nexport type ExtendWithSystemFields<\n  TableName extends string,\n  TableSchema extends Schema.Top,\n> =\n  TableSchema extends Schema.Union<\n    infer Members extends ReadonlyArray<Schema.Top>\n  >\n    ? Schema.Union<\n        Struct.Simplify<\n          Readonly<{\n            [K in keyof Members]: ExtendWithSystemFields<TableName, Members[K]>;\n          }>\n        >\n      >\n    : ApplySystemFields<TableName, TableSchema>;\n\n/**\n * The decoded/encoded document shape: a table's fields plus Convex's system\n * fields. Deliberately a bare intersection (no `Expand`/`Simplify`)—flattening\n * it with a homomorphic mapped type collapses to `{ [x: string]: any }` when\n * `Document` is still an unresolved generic, which breaks structural\n * comparability in the database reader/writer plumbing.\n */\nexport type WithSystemFields<\n  TableName extends string,\n  Document,\n> = Document extends unknown\n  ? IdField<TableName> & NonIdSystemFields & Document\n  : never;\n"],"mappings":"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"}

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@confect/core",
   "description": "Shared specs and schemas used by all Confect packages",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0",
-    "@types/node": "24.13.3",
+    "@effect/vitest": "4.0.1",
+    "@types/node": "26.6.4",
     "confect-bench-harness": "0.0.0",
-    "effect": "4.0.0",
+    "effect": "4.0.1",
     "tsdown": "0.23.0",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
     "unrun": "0.3.1",
-    "vitest": "5.0.2"
+    "vitest": "5.0.3"
   },
   "engines": {
     "node": ">=24"

package/src/SystemFields.ts

@@ -153,15 +153,15 @@ const makeExtendAst = (
 /**
  * Extend a table schema with Convex system fields.
  *
- * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union` has
- * them distributed across its members, preserving the schema's `Struct`/`Union`
- * structure. Any other object-shaped schema—one built with
- * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended
- * schema—is extended at the AST level: every object node in its encoding chain
- * gains the system fields, and each transformation is wrapped so the fields
- * bypass the user-defined getters. Schemas that do not resolve to an object
- * shape at every step (such as `Schema.Class`, whose decoded values are class
- * instances) are rejected with a descriptive error.
+ * A plain `Struct` gains the fields via `mapFields` and a `Union` has them
+ * distributed across its members via `mapMembers`, preserving the schema's
+ * checks and `Struct`/`Union` structure. Any other object-shaped schema—one
+ * built with `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a
+ * suspended schema—is extended at the AST level: every object node in its
+ * encoding chain gains the system fields, and each transformation is wrapped so
+ * the fields bypass the user-defined getters. Schemas that do not resolve to an
+ * object shape at every step (such as `Schema.Class`, whose decoded values are
+ * class instances) are rejected with a descriptive error.
  *
  * Note that struct-level checks on an extended schema observe the value with
  * the system fields attached, and encoding an extended schema emits the system
@@ -192,11 +192,9 @@ export const extendWithSystemFields = <
       SchemaAST.isUnion(s.ast) &&
       Array.isArray((s as { readonly members?: unknown }).members)
     ) {
-      return Schema.Union(
-        Array.map(
-          (s as Schema.Union<ReadonlyArray<Schema.Top>>).members,
-          extend,
-        ),
+      return (s as Schema.Union<ReadonlyArray<Schema.Top>>).mapMembers(
+        Array.map(extend),
+        { unsafePreserveChecks: true },
       );
     }
     if (
@@ -204,8 +202,9 @@ export const extendWithSystemFields = <
       SchemaAST.isObjects(s.ast) &&
       typeof (s as { readonly mapFields?: unknown }).mapFields === "function"
     ) {
-      return Schema.fieldsAssign(system)(
-        s as Schema.Struct<Schema.Struct.Fields>,
+      return (s as Schema.Struct<Schema.Struct.Fields>).mapFields(
+        Struct.assign(system),
+        { unsafePreserveChecks: true },
       );
     }
     return Schema.make(extendAst(s.ast));