@entifix/core 0.1.0-0

package/dist/entity-definition/metadata/entity-metadata-source.js

@@ -0,0 +1,15 @@
+/**
+ * Where a UI gets an entity's {@link EntityMetadataDocument} from.
+ *
+ * A port, for the same reason `EntityLinkSource` is one: the implementation that
+ * fetches lives in the client layer, the components that render live in the
+ * controls layer, and those two may not import each other — this contract in
+ * `core` is what lets them meet. It carries no Effect and no React deliberately.
+ *
+ * The indirection is also what keeps use-case *implementations* out of a client
+ * bundle. A browser must never import a `@useCase()` class: that would drag its
+ * `Effect` body, its repository tags and its whole import closure across the
+ * wire. It fetches descriptors instead.
+ */ export { };
+
+//# sourceMappingURL=entity-metadata-source.js.map

package/dist/entity-definition/metadata/entity-metadata-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/metadata/entity-metadata-source.ts"],"sourcesContent":["import type { Entity, EntityConstructor } from '../../types/Entity.js';\nimport type { EntityMetadataDocument } from './entity-metadata-document.js';\n\n/**\n * Where a UI gets an entity's {@link EntityMetadataDocument} from.\n *\n * A port, for the same reason `EntityLinkSource` is one: the implementation that\n * fetches lives in the client layer, the components that render live in the\n * controls layer, and those two may not import each other — this contract in\n * `core` is what lets them meet. It carries no Effect and no React deliberately.\n *\n * The indirection is also what keeps use-case *implementations* out of a client\n * bundle. A browser must never import a `@useCase()` class: that would drag its\n * `Effect` body, its repository tags and its whole import closure across the\n * wire. It fetches descriptors instead.\n */\nexport interface EntityMetadataSource {\n  fetchMetadata<TEntity extends Entity>(\n    entityConstructor: EntityConstructor<TEntity>,\n  ): Promise<EntityMetadataDocument>;\n}\n"],"names":[],"mappings":"AAGA;;;;;;;;;;;;CAYC,GACD,WAIC"}

package/dist/entity-definition/metadata/index.d.ts

@@ -0,0 +1,3 @@
+export * from './entity-metadata-document.js';
+export * from './entity-metadata-source.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/metadata/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC"}

package/dist/entity-definition/metadata/index.js

@@ -0,0 +1,4 @@
+export * from './entity-metadata-document.js';
+export * from './entity-metadata-source.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/metadata/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/metadata/index.ts"],"sourcesContent":["export * from './entity-metadata-document.js';\nexport * from './entity-metadata-source.js';\n"],"names":[],"mappings":"AAAA,cAAc,gCAAgC;AAC9C,cAAc,8BAA8B"}

package/dist/entity-definition/reconstruct/clone-entity-draft.d.ts

@@ -0,0 +1,34 @@
+import { Entity, EntityConstructor } from '../../types/Entity.js';
+import { EntityDraft } from '../../types/EntityDraft.js';
+/**
+ * The draft for a copy of a record: everything the original held, minus the
+ * members a copy must not carry.
+ *
+ * **A draft in and a draft out**, rather than an instance in and an instance
+ * out, and that is the whole reason this composes with the rest of the form
+ * layer. A form's state is a `Record<string, string>` that a workspace
+ * autosaves (ADR 0032), so a clone that returned an instance would have to be
+ * re-seeded back into a draft by the caller — through `seedFieldValue`, which
+ * lives in a package above this one. Staying in the draft keeps the operation
+ * on one side of that boundary, and `reconstructEntity` is still what turns the
+ * result into an entity at submit.
+ *
+ * Two kinds of member are dropped:
+ *
+ * - **the identity member**, always, with no flag — a copy that carries the
+ *   original's `id` is an update to the original, which is the one outcome a
+ *   Clone button must never produce;
+ * - **anything declared `@accessor({ resetOnClone: true })`** — a unique code,
+ *   an audit stamp, a sequence number.
+ *
+ * Cleared to `''` rather than deleted, because `''` is what an empty control
+ * drafts as: a member removed from the record entirely would arrive
+ * `undefined`, and an input handed `undefined` flips from controlled to
+ * uncontrolled — the same trap `restoreEntityDraft` layers a restored draft
+ * over a seeded one to avoid.
+ *
+ * A member the entity declares but the draft never held stays absent, so this
+ * neither invents keys nor widens the draft.
+ */
+export declare function cloneEntityDraft<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, values: EntityDraft): EntityDraft;
+//# sourceMappingURL=clone-entity-draft.d.ts.map

package/dist/entity-definition/reconstruct/clone-entity-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-entity-draft.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/reconstruct/clone-entity-draft.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAyB,MAAM,4BAA4B,CAAC;AAWhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,MAAM,EACrD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,EAAE,WAAW,GAClB,WAAW,CA0Bb"}

package/dist/entity-definition/reconstruct/clone-entity-draft.js

@@ -0,0 +1,75 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { newRowKey, readRowDrafts, ROW_KEY } from '../../types/EntityRowDraft.js';
+import { describeEntityColumns } from '../describe/index.js';
+/** The member `Entity` requires every record to carry. */ const ID_MEMBER = 'id';
+/**
+ * The draft for a copy of a record: everything the original held, minus the
+ * members a copy must not carry.
+ *
+ * **A draft in and a draft out**, rather than an instance in and an instance
+ * out, and that is the whole reason this composes with the rest of the form
+ * layer. A form's state is a `Record<string, string>` that a workspace
+ * autosaves (ADR 0032), so a clone that returned an instance would have to be
+ * re-seeded back into a draft by the caller — through `seedFieldValue`, which
+ * lives in a package above this one. Staying in the draft keeps the operation
+ * on one side of that boundary, and `reconstructEntity` is still what turns the
+ * result into an entity at submit.
+ *
+ * Two kinds of member are dropped:
+ *
+ * - **the identity member**, always, with no flag — a copy that carries the
+ *   original's `id` is an update to the original, which is the one outcome a
+ *   Clone button must never produce;
+ * - **anything declared `@accessor({ resetOnClone: true })`** — a unique code,
+ *   an audit stamp, a sequence number.
+ *
+ * Cleared to `''` rather than deleted, because `''` is what an empty control
+ * drafts as: a member removed from the record entirely would arrive
+ * `undefined`, and an input handed `undefined` flips from controlled to
+ * uncontrolled — the same trap `restoreEntityDraft` layers a restored draft
+ * over a seeded one to avoid.
+ *
+ * A member the entity declares but the draft never held stays absent, so this
+ * neither invents keys nor widens the draft.
+ */ export function cloneEntityDraft(entityConstructor, values) {
+    const cloned = _extends({}, values);
+    // The identity member, cleared **without consulting the descriptors**.
+    // `describeEntityColumns` drops `hidden` members, and a form hiding its id is
+    // the ordinary case rather than the exotic one — every generated catalog page
+    // does it — so a descriptor-driven sweep would leave the id in place on
+    // exactly the forms a Clone button appears on, and the "copy" would silently
+    // save over the original. `Entity` fixes this member's name, so there is no
+    // metadata to consult anyway.
+    if (ID_MEMBER in cloned) cloned[ID_MEMBER] = '';
+    for (const descriptor of describeEntityColumns(entityConstructor)){
+        if (descriptor.type === 'composition') {
+            cloned[descriptor.name] = clonedRows(cloned[descriptor.name], descriptor.resetOnClone);
+            continue;
+        }
+        if (descriptor.type !== 'id' && !descriptor.resetOnClone) continue;
+        if (!(descriptor.name in cloned)) continue;
+        cloned[descriptor.name] = '';
+    }
+    return cloned;
+}
+/**
+ * The rows a copy starts with.
+ *
+ * Two things the `''` rule above cannot express. A collection is **emptied to
+ * `[]`, never to `''`**: an empty string is not a readable row list, so
+ * `reconstructEntity` would skip the member and the "reset" collection would
+ * come back holding the original's lines — a `resetOnClone` that resets nothing.
+ *
+ * And a row that *is* copied gets a **fresh key**. The key identifies a row
+ * within one editing session; carrying the original's over means the copy and
+ * the original name their lines identically, so a workspace holding both open
+ * has two tabs whose rows claim the same identity — harmless until anything
+ * addresses a row across them, and impossible to debug once it does.
+ */ function clonedRows(value, reset) {
+    if (reset) return [];
+    return readRowDrafts(value).map((row)=>_extends({}, row, {
+            [ROW_KEY]: newRowKey()
+        }));
+}
+
+//# sourceMappingURL=clone-entity-draft.js.map

package/dist/entity-definition/reconstruct/clone-entity-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/reconstruct/clone-entity-draft.ts"],"sourcesContent":["import { Entity, EntityConstructor } from '../../types/Entity.js';\nimport { EntityDraft, type EntityDraftValue } from '../../types/EntityDraft.js';\nimport {\n  newRowKey,\n  readRowDrafts,\n  ROW_KEY,\n} from '../../types/EntityRowDraft.js';\nimport { describeEntityColumns } from '../describe/index.js';\n\n/** The member `Entity` requires every record to carry. */\nconst ID_MEMBER = 'id';\n\n/**\n * The draft for a copy of a record: everything the original held, minus the\n * members a copy must not carry.\n *\n * **A draft in and a draft out**, rather than an instance in and an instance\n * out, and that is the whole reason this composes with the rest of the form\n * layer. A form's state is a `Record<string, string>` that a workspace\n * autosaves (ADR 0032), so a clone that returned an instance would have to be\n * re-seeded back into a draft by the caller — through `seedFieldValue`, which\n * lives in a package above this one. Staying in the draft keeps the operation\n * on one side of that boundary, and `reconstructEntity` is still what turns the\n * result into an entity at submit.\n *\n * Two kinds of member are dropped:\n *\n * - **the identity member**, always, with no flag — a copy that carries the\n *   original's `id` is an update to the original, which is the one outcome a\n *   Clone button must never produce;\n * - **anything declared `@accessor({ resetOnClone: true })`** — a unique code,\n *   an audit stamp, a sequence number.\n *\n * Cleared to `''` rather than deleted, because `''` is what an empty control\n * drafts as: a member removed from the record entirely would arrive\n * `undefined`, and an input handed `undefined` flips from controlled to\n * uncontrolled — the same trap `restoreEntityDraft` layers a restored draft\n * over a seeded one to avoid.\n *\n * A member the entity declares but the draft never held stays absent, so this\n * neither invents keys nor widens the draft.\n */\nexport function cloneEntityDraft<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  values: EntityDraft,\n): EntityDraft {\n  const cloned: EntityDraft = { ...values };\n\n  // The identity member, cleared **without consulting the descriptors**.\n  // `describeEntityColumns` drops `hidden` members, and a form hiding its id is\n  // the ordinary case rather than the exotic one — every generated catalog page\n  // does it — so a descriptor-driven sweep would leave the id in place on\n  // exactly the forms a Clone button appears on, and the \"copy\" would silently\n  // save over the original. `Entity` fixes this member's name, so there is no\n  // metadata to consult anyway.\n  if (ID_MEMBER in cloned) cloned[ID_MEMBER] = '';\n\n  for (const descriptor of describeEntityColumns(entityConstructor)) {\n    if (descriptor.type === 'composition') {\n      cloned[descriptor.name] = clonedRows(\n        cloned[descriptor.name],\n        descriptor.resetOnClone,\n      );\n      continue;\n    }\n    if (descriptor.type !== 'id' && !descriptor.resetOnClone) continue;\n    if (!(descriptor.name in cloned)) continue;\n    cloned[descriptor.name] = '';\n  }\n\n  return cloned;\n}\n\n/**\n * The rows a copy starts with.\n *\n * Two things the `''` rule above cannot express. A collection is **emptied to\n * `[]`, never to `''`**: an empty string is not a readable row list, so\n * `reconstructEntity` would skip the member and the \"reset\" collection would\n * come back holding the original's lines — a `resetOnClone` that resets nothing.\n *\n * And a row that *is* copied gets a **fresh key**. The key identifies a row\n * within one editing session; carrying the original's over means the copy and\n * the original name their lines identically, so a workspace holding both open\n * has two tabs whose rows claim the same identity — harmless until anything\n * addresses a row across them, and impossible to debug once it does.\n */\nfunction clonedRows(\n  value: EntityDraftValue | undefined,\n  reset: boolean,\n): EntityDraftValue {\n  if (reset) return [];\n  return readRowDrafts(value).map(row => ({ ...row, [ROW_KEY]: newRowKey() }));\n}\n"],"names":["newRowKey","readRowDrafts","ROW_KEY","describeEntityColumns","ID_MEMBER","cloneEntityDraft","entityConstructor","values","cloned","descriptor","type","name","clonedRows","resetOnClone","value","reset","map","row"],"mappings":";AAEA,SACEA,SAAS,EACTC,aAAa,EACbC,OAAO,QACF,gCAAgC;AACvC,SAASC,qBAAqB,QAAQ,uBAAuB;AAE7D,wDAAwD,GACxD,MAAMC,YAAY;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD,OAAO,SAASC,iBACdC,iBAA6C,EAC7CC,MAAmB;IAEnB,MAAMC,SAAsB,aAAKD;IAEjC,uEAAuE;IACvE,8EAA8E;IAC9E,8EAA8E;IAC9E,wEAAwE;IACxE,6EAA6E;IAC7E,4EAA4E;IAC5E,8BAA8B;IAC9B,IAAIH,aAAaI,QAAQA,MAAM,CAACJ,UAAU,GAAG;IAE7C,KAAK,MAAMK,cAAcN,sBAAsBG,mBAAoB;QACjE,IAAIG,WAAWC,IAAI,KAAK,eAAe;YACrCF,MAAM,CAACC,WAAWE,IAAI,CAAC,GAAGC,WACxBJ,MAAM,CAACC,WAAWE,IAAI,CAAC,EACvBF,WAAWI,YAAY;YAEzB;QACF;QACA,IAAIJ,WAAWC,IAAI,KAAK,QAAQ,CAACD,WAAWI,YAAY,EAAE;QAC1D,IAAI,CAAEJ,CAAAA,WAAWE,IAAI,IAAIH,MAAK,GAAI;QAClCA,MAAM,CAACC,WAAWE,IAAI,CAAC,GAAG;IAC5B;IAEA,OAAOH;AACT;AAEA;;;;;;;;;;;;;CAaC,GACD,SAASI,WACPE,KAAmC,EACnCC,KAAc;IAEd,IAAIA,OAAO,OAAO,EAAE;IACpB,OAAOd,cAAca,OAAOE,GAAG,CAACC,CAAAA,MAAQ,aAAKA;YAAK,CAACf,QAAQ,EAAEF;;AAC/D"}

package/dist/entity-definition/reconstruct/coerce-field-value.d.ts

@@ -0,0 +1,34 @@
+import type { EntityFieldDescriptor } from '../describe/index.js';
+/**
+ * The typed value a draft string stands for.
+ *
+ * This is the exact inverse of the form layer's `seedFieldValue`, and the two
+ * have to agree or the round trip is lossy — a member seeded from a record and
+ * submitted untouched must come back equal. Two rules are not obvious:
+ *
+ * - **`boolean` is decided before the empty check, and never yields
+ *   `undefined`.** A checkbox renders `''` as unchecked, so `''` means `false`;
+ *   letting the blanket empty rule run first would write `undefined` where the
+ *   user saw a box they had deliberately left clear.
+ * - **`number` checks empty first.** `Number('')` is `0`, so the other order
+ *   turns every blank numeric field into a real zero.
+ *
+ * A malformed `number` or `date` is passed through as `NaN` / an invalid `Date`
+ * rather than dropped: the form's metadata validation rejects both before
+ * submit, and silently discarding a value the user typed would be worse than
+ * surfacing it.
+ *
+ * `scalarCollection` is the one collection with a lossless string form, so it
+ * round-trips here rather than waiting for an editor: a comma list in, a
+ * `string[]` out. It reads **empty as `[]`, never `undefined`** — a member the
+ * user cleared holds no values, which is a different fact from a member that
+ * was never set, and only the empty array survives a `required` check honestly.
+ * `composition` has no string form at all and never reaches this function; its
+ * rows are rebuilt by `reconstructChild`.
+ *
+ * Extracted from `reconstructEntity` so that a composition's rows coerce through
+ * the **same** function their master's scalars do. Two copies of these rules is
+ * how a child's `number` member would quietly start meaning something else.
+ */
+export declare function coerceFieldValue(descriptor: EntityFieldDescriptor, raw: string): unknown;
+//# sourceMappingURL=coerce-field-value.d.ts.map

package/dist/entity-definition/reconstruct/coerce-field-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce-field-value.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/reconstruct/coerce-field-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,qBAAqB,EACjC,GAAG,EAAE,MAAM,GACV,OAAO,CAST"}

package/dist/entity-definition/reconstruct/coerce-field-value.js

@@ -0,0 +1,42 @@
+/**
+ * The typed value a draft string stands for.
+ *
+ * This is the exact inverse of the form layer's `seedFieldValue`, and the two
+ * have to agree or the round trip is lossy — a member seeded from a record and
+ * submitted untouched must come back equal. Two rules are not obvious:
+ *
+ * - **`boolean` is decided before the empty check, and never yields
+ *   `undefined`.** A checkbox renders `''` as unchecked, so `''` means `false`;
+ *   letting the blanket empty rule run first would write `undefined` where the
+ *   user saw a box they had deliberately left clear.
+ * - **`number` checks empty first.** `Number('')` is `0`, so the other order
+ *   turns every blank numeric field into a real zero.
+ *
+ * A malformed `number` or `date` is passed through as `NaN` / an invalid `Date`
+ * rather than dropped: the form's metadata validation rejects both before
+ * submit, and silently discarding a value the user typed would be worse than
+ * surfacing it.
+ *
+ * `scalarCollection` is the one collection with a lossless string form, so it
+ * round-trips here rather than waiting for an editor: a comma list in, a
+ * `string[]` out. It reads **empty as `[]`, never `undefined`** — a member the
+ * user cleared holds no values, which is a different fact from a member that
+ * was never set, and only the empty array survives a `required` check honestly.
+ * `composition` has no string form at all and never reaches this function; its
+ * rows are rebuilt by `reconstructChild`.
+ *
+ * Extracted from `reconstructEntity` so that a composition's rows coerce through
+ * the **same** function their master's scalars do. Two copies of these rules is
+ * how a child's `number` member would quietly start meaning something else.
+ */ export function coerceFieldValue(descriptor, raw) {
+    if (descriptor.type === 'boolean') return raw === 'true';
+    if (descriptor.type === 'scalarCollection') {
+        return raw === '' ? [] : raw.split(',');
+    }
+    if (raw === '') return undefined;
+    if (descriptor.type === 'number') return Number(raw);
+    if (descriptor.type === 'date') return new Date(raw);
+    return raw;
+}
+
+//# sourceMappingURL=coerce-field-value.js.map

package/dist/entity-definition/reconstruct/coerce-field-value.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/reconstruct/coerce-field-value.ts"],"sourcesContent":["import type { EntityFieldDescriptor } from '../describe/index.js';\n\n/**\n * The typed value a draft string stands for.\n *\n * This is the exact inverse of the form layer's `seedFieldValue`, and the two\n * have to agree or the round trip is lossy — a member seeded from a record and\n * submitted untouched must come back equal. Two rules are not obvious:\n *\n * - **`boolean` is decided before the empty check, and never yields\n *   `undefined`.** A checkbox renders `''` as unchecked, so `''` means `false`;\n *   letting the blanket empty rule run first would write `undefined` where the\n *   user saw a box they had deliberately left clear.\n * - **`number` checks empty first.** `Number('')` is `0`, so the other order\n *   turns every blank numeric field into a real zero.\n *\n * A malformed `number` or `date` is passed through as `NaN` / an invalid `Date`\n * rather than dropped: the form's metadata validation rejects both before\n * submit, and silently discarding a value the user typed would be worse than\n * surfacing it.\n *\n * `scalarCollection` is the one collection with a lossless string form, so it\n * round-trips here rather than waiting for an editor: a comma list in, a\n * `string[]` out. It reads **empty as `[]`, never `undefined`** — a member the\n * user cleared holds no values, which is a different fact from a member that\n * was never set, and only the empty array survives a `required` check honestly.\n * `composition` has no string form at all and never reaches this function; its\n * rows are rebuilt by `reconstructChild`.\n *\n * Extracted from `reconstructEntity` so that a composition's rows coerce through\n * the **same** function their master's scalars do. Two copies of these rules is\n * how a child's `number` member would quietly start meaning something else.\n */\nexport function coerceFieldValue(\n  descriptor: EntityFieldDescriptor,\n  raw: string,\n): unknown {\n  if (descriptor.type === 'boolean') return raw === 'true';\n  if (descriptor.type === 'scalarCollection') {\n    return raw === '' ? [] : raw.split(',');\n  }\n  if (raw === '') return undefined;\n  if (descriptor.type === 'number') return Number(raw);\n  if (descriptor.type === 'date') return new Date(raw);\n  return raw;\n}\n"],"names":["coerceFieldValue","descriptor","raw","type","split","undefined","Number","Date"],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASA,iBACdC,UAAiC,EACjCC,GAAW;IAEX,IAAID,WAAWE,IAAI,KAAK,WAAW,OAAOD,QAAQ;IAClD,IAAID,WAAWE,IAAI,KAAK,oBAAoB;QAC1C,OAAOD,QAAQ,KAAK,EAAE,GAAGA,IAAIE,KAAK,CAAC;IACrC;IACA,IAAIF,QAAQ,IAAI,OAAOG;IACvB,IAAIJ,WAAWE,IAAI,KAAK,UAAU,OAAOG,OAAOJ;IAChD,IAAID,WAAWE,IAAI,KAAK,QAAQ,OAAO,IAAII,KAAKL;IAChD,OAAOA;AACT"}

package/dist/entity-definition/reconstruct/index.d.ts

@@ -0,0 +1,5 @@
+export * from './clone-entity-draft.js';
+export * from './coerce-field-value.js';
+export * from './reconstruct-child.js';
+export * from './reconstruct-entity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/reconstruct/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/reconstruct/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC"}

package/dist/entity-definition/reconstruct/index.js

@@ -0,0 +1,6 @@
+export * from './clone-entity-draft.js';
+export * from './coerce-field-value.js';
+export * from './reconstruct-child.js';
+export * from './reconstruct-entity.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/reconstruct/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/reconstruct/index.ts"],"sourcesContent":["export * from './clone-entity-draft.js';\nexport * from './coerce-field-value.js';\nexport * from './reconstruct-child.js';\nexport * from './reconstruct-entity.js';\n"],"names":[],"mappings":"AAAA,cAAc,0BAA0B;AACxC,cAAc,0BAA0B;AACxC,cAAc,yBAAyB;AACvC,cAAc,0BAA0B"}

package/dist/entity-definition/reconstruct/reconstruct-child.d.ts

@@ -0,0 +1,35 @@
+import type { EntityRowDraft } from '../../types/EntityRowDraft.js';
+import type { ChildConstructor } from '../meta-entities/meta-accessor/index.js';
+/**
+ * Rebuilds one owned row from its draft.
+ *
+ * The master's own `reconstructEntity` in miniature, and deliberately the same
+ * shape: construct zero-argument, then assign through setters, coercing each
+ * draft string with the **same** `coerceFieldValue` the master's scalars use.
+ * A child that declares `quantity` as a `number` therefore means the same thing
+ * on a line as it would on a record.
+ *
+ * Three rules that are not obvious from the body.
+ *
+ * **The row key never reaches the child.** It is the browser's identity for the
+ * row, not the entity's data — the child is a *value* with no `id` at all — so
+ * writing it would put a member on the wire the entity never declared. There is
+ * no check for it here because there cannot be one to make: the walk is driven
+ * by `describeChildColumns`, which *throws* on a child declaring that name, so
+ * no descriptor can ever carry it. A guard here would be unreachable code
+ * standing in for an invariant that is already enforced.
+ *
+ * **A child is never `instanceof`-tested.** `ChildConstructor` is a shape
+ * declaration: a row arriving off the wire is a plain object and a row arriving
+ * from a draft is JSON, so the constructed instance is the only place the class
+ * is real. That is also why the assignment is by `descriptor.name` and not
+ * `descriptor.key` — `key` is `alias ?? name`, the storage column, which
+ * `serializeEntity` applies a moment later on the way out.
+ *
+ * **Read-only and nested-collection members are skipped**, matching
+ * `editableChildColumns`: a grid cannot write the first, and the second would
+ * need a grid inside a grid, which `reconstructChild` is one level too shallow
+ * to build by decision rather than by omission.
+ */
+export declare function reconstructChild<TChild extends object>(childType: ChildConstructor<TChild>, row: EntityRowDraft): TChild;
+//# sourceMappingURL=reconstruct-child.d.ts.map

package/dist/entity-definition/reconstruct/reconstruct-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconstruct-child.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/reconstruct/reconstruct-child.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAGhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,EACpD,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,EACnC,GAAG,EAAE,cAAc,GAClB,MAAM,CAqBR"}

package/dist/entity-definition/reconstruct/reconstruct-child.js

@@ -0,0 +1,47 @@
+import { describeChildColumns } from '../describe/index.js';
+import { coerceFieldValue } from './coerce-field-value.js';
+/**
+ * Rebuilds one owned row from its draft.
+ *
+ * The master's own `reconstructEntity` in miniature, and deliberately the same
+ * shape: construct zero-argument, then assign through setters, coercing each
+ * draft string with the **same** `coerceFieldValue` the master's scalars use.
+ * A child that declares `quantity` as a `number` therefore means the same thing
+ * on a line as it would on a record.
+ *
+ * Three rules that are not obvious from the body.
+ *
+ * **The row key never reaches the child.** It is the browser's identity for the
+ * row, not the entity's data — the child is a *value* with no `id` at all — so
+ * writing it would put a member on the wire the entity never declared. There is
+ * no check for it here because there cannot be one to make: the walk is driven
+ * by `describeChildColumns`, which *throws* on a child declaring that name, so
+ * no descriptor can ever carry it. A guard here would be unreachable code
+ * standing in for an invariant that is already enforced.
+ *
+ * **A child is never `instanceof`-tested.** `ChildConstructor` is a shape
+ * declaration: a row arriving off the wire is a plain object and a row arriving
+ * from a draft is JSON, so the constructed instance is the only place the class
+ * is real. That is also why the assignment is by `descriptor.name` and not
+ * `descriptor.key` — `key` is `alias ?? name`, the storage column, which
+ * `serializeEntity` applies a moment later on the way out.
+ *
+ * **Read-only and nested-collection members are skipped**, matching
+ * `editableChildColumns`: a grid cannot write the first, and the second would
+ * need a grid inside a grid, which `reconstructChild` is one level too shallow
+ * to build by decision rather than by omission.
+ */ export function reconstructChild(childType, row) {
+    const instance = new childType();
+    for (const descriptor of describeChildColumns(childType, instance)){
+        var _row_descriptor_name;
+        if (descriptor.readonly) continue;
+        if (descriptor.type === 'composition' || descriptor.type === 'linkCollection' || descriptor.type === 'link') {
+            continue;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        instance[descriptor.name] = coerceFieldValue(descriptor, (_row_descriptor_name = row[descriptor.name]) != null ? _row_descriptor_name : '');
+    }
+    return instance;
+}
+
+//# sourceMappingURL=reconstruct-child.js.map

package/dist/entity-definition/reconstruct/reconstruct-child.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/reconstruct/reconstruct-child.ts"],"sourcesContent":["import type { EntityRowDraft } from '../../types/EntityRowDraft.js';\nimport { describeChildColumns } from '../describe/index.js';\nimport type { ChildConstructor } from '../meta-entities/meta-accessor/index.js';\nimport { coerceFieldValue } from './coerce-field-value.js';\n\n/**\n * Rebuilds one owned row from its draft.\n *\n * The master's own `reconstructEntity` in miniature, and deliberately the same\n * shape: construct zero-argument, then assign through setters, coercing each\n * draft string with the **same** `coerceFieldValue` the master's scalars use.\n * A child that declares `quantity` as a `number` therefore means the same thing\n * on a line as it would on a record.\n *\n * Three rules that are not obvious from the body.\n *\n * **The row key never reaches the child.** It is the browser's identity for the\n * row, not the entity's data — the child is a *value* with no `id` at all — so\n * writing it would put a member on the wire the entity never declared. There is\n * no check for it here because there cannot be one to make: the walk is driven\n * by `describeChildColumns`, which *throws* on a child declaring that name, so\n * no descriptor can ever carry it. A guard here would be unreachable code\n * standing in for an invariant that is already enforced.\n *\n * **A child is never `instanceof`-tested.** `ChildConstructor` is a shape\n * declaration: a row arriving off the wire is a plain object and a row arriving\n * from a draft is JSON, so the constructed instance is the only place the class\n * is real. That is also why the assignment is by `descriptor.name` and not\n * `descriptor.key` — `key` is `alias ?? name`, the storage column, which\n * `serializeEntity` applies a moment later on the way out.\n *\n * **Read-only and nested-collection members are skipped**, matching\n * `editableChildColumns`: a grid cannot write the first, and the second would\n * need a grid inside a grid, which `reconstructChild` is one level too shallow\n * to build by decision rather than by omission.\n */\nexport function reconstructChild<TChild extends object>(\n  childType: ChildConstructor<TChild>,\n  row: EntityRowDraft,\n): TChild {\n  const instance = new childType();\n\n  for (const descriptor of describeChildColumns(childType, instance)) {\n    if (descriptor.readonly) continue;\n    if (\n      descriptor.type === 'composition' ||\n      descriptor.type === 'linkCollection' ||\n      descriptor.type === 'link'\n    ) {\n      continue;\n    }\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (instance as any)[descriptor.name] = coerceFieldValue(\n      descriptor,\n      row[descriptor.name] ?? '',\n    );\n  }\n\n  return instance;\n}\n"],"names":["describeChildColumns","coerceFieldValue","reconstructChild","childType","row","instance","descriptor","readonly","type","name"],"mappings":"AACA,SAASA,oBAAoB,QAAQ,uBAAuB;AAE5D,SAASC,gBAAgB,QAAQ,0BAA0B;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASC,iBACdC,SAAmC,EACnCC,GAAmB;IAEnB,MAAMC,WAAW,IAAIF;IAErB,KAAK,MAAMG,cAAcN,qBAAqBG,WAAWE,UAAW;YAahED;QAZF,IAAIE,WAAWC,QAAQ,EAAE;QACzB,IACED,WAAWE,IAAI,KAAK,iBACpBF,WAAWE,IAAI,KAAK,oBACpBF,WAAWE,IAAI,KAAK,QACpB;YACA;QACF;QAEA,8DAA8D;QAC7DH,QAAgB,CAACC,WAAWG,IAAI,CAAC,GAAGR,iBACnCK,aACAF,uBAAAA,GAAG,CAACE,WAAWG,IAAI,CAAC,YAApBL,uBAAwB;IAE5B;IAEA,OAAOC;AACT"}

package/dist/entity-definition/reconstruct/reconstruct-entity.d.ts

@@ -0,0 +1,49 @@
+import { Entity, EntityConstructor } from '../../types/Entity.js';
+import { EntityDraft } from '../../types/EntityDraft.js';
+import { type EntityLinkSelection } from '../links/apply-entity-links/index.js';
+/** Everything {@link reconstructEntity} needs beyond the draft itself. */
+export interface ReconstructEntityOptions<TEntity extends Entity> {
+    /**
+     * The record being edited. Supplies the `id` and nothing else — see
+     * {@link reconstructEntity} on why it is only the id.
+     */
+    existing?: TEntity;
+    /**
+     * The instances a picker handed over, for members whose declared
+     * `linkSerialization` is `embedded`. Passed straight to `applyEntityLinks`.
+     */
+    selection?: EntityLinkSelection;
+}
+/**
+ * Rebuilds a domain instance from a form's string draft, deriving every
+ * assignment from the entity's own accessor metadata.
+ *
+ * This is the one genuinely hand-written part of an entity form, and writing it
+ * per entity is a bug farm: each one repeats the same empty-string-to-undefined
+ * rule, and each one has to remember to carry back a member the form hides —
+ * `ProductBrand.code` is assigned by the create transaction, and dropping it
+ * blanks the record's identifier on every update. Deriving the walk from the
+ * metadata makes that structural instead of remembered.
+ *
+ * **Construction is zero-argument.** `new entityConstructor()` then assignment
+ * through setters, the same shape `buildEntityInstance` uses to rebuild a record
+ * off the wire. Entities default their constructor parameters, and a required
+ * member is filled by its setter a moment later — so required-ness stays one
+ * fact (the `@accessor({ required })` flag the form already validates against)
+ * rather than a second, unverifiable list of constructor argument names.
+ *
+ * Constructing first also gives `describeEntityColumns` a sample, which is what
+ * lets it infer `link`-ness for an accessor that declared no `type`: relations
+ * are initialized by the constructor, so the fresh instance already carries them.
+ *
+ * **`existing` supplies the id and nothing else.** Every other member comes from
+ * the draft, which was seeded from the record — so a create/update distinction
+ * lives here once instead of a `target.id = entity?.id` line per form. A draft
+ * may be client-supplied (a workspace autosaves it), which is not a new surface:
+ * a save route already overwrites the id from its own route parameter.
+ *
+ * Pure and framework-free, so the same reconstruction runs in a browser form and
+ * in a backend use-case assembling an entity from a raw draft.
+ */
+export declare function reconstructEntity<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, values: EntityDraft, { existing, selection }?: ReconstructEntityOptions<TEntity>): TEntity;
+//# sourceMappingURL=reconstruct-entity.d.ts.map

package/dist/entity-definition/reconstruct/reconstruct-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconstruct-entity.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/reconstruct/reconstruct-entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAmB,MAAM,4BAA4B,CAAC;AAM1E,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,sCAAsC,CAAC;AAM9C,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,MAAM;IAC9D;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAmFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,EACtD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,EAAE,WAAW,EACnB,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAE,wBAAwB,CAAC,OAAO,CAAM,GAC9D,OAAO,CAwBT"}

package/dist/entity-definition/reconstruct/reconstruct-entity.js

@@ -0,0 +1,116 @@
+import { readDraftString } from '../../types/EntityDraft.js';
+import { isRowDraftArray } from '../../types/EntityRowDraft.js';
+import { describeEntityColumns } from '../describe/index.js';
+import { applyEntityLinks } from '../links/apply-entity-links/index.js';
+import { EntityCollectionLink } from '../links/entity-collection-link/index.js';
+import { EntityLink } from '../links/entity-link/index.js';
+import { coerceFieldValue } from './coerce-field-value.js';
+import { reconstructChild } from './reconstruct-child.js';
+/**
+ * Writes an entity's owned collections back from the rows its draft holds.
+ *
+ * A **second pass** rather than a branch inside the scalar walk, and the reason
+ * is the invariant it protects: `isWritableScalar` must go on refusing
+ * `composition`, because assigning a coerced string to a member that holds rows
+ * is how the master's own lines get blanked on a save that touches nothing else.
+ * Keeping the two walks separate means a `composition` is written by exactly one
+ * piece of code, and that code cannot be reached with a string.
+ *
+ * A member whose draft entry is missing or unreadable is **skipped, not
+ * cleared** — the same rule the scalar walk applies to a member the form hides.
+ * A draft written before this member existed, or one restored from a build that
+ * did not know it, must leave the record's rows exactly as they were rather than
+ * emptying them, which is a data loss the user never asked for and cannot see.
+ * An explicitly empty list *is* a value and is written: that is a user who
+ * removed every row.
+ *
+ * Read-only is honoured for the same reason as everywhere else, and the
+ * `childType` guard is not defensive — a `composition` that declared no child
+ * has no columns to coerce against, so there is nothing to rebuild.
+ */ function applyEntityComposition(instance, descriptors, values) {
+    for (const descriptor of descriptors){
+        if (descriptor.type !== 'composition') continue;
+        if (descriptor.readonly || descriptor.childType === undefined) continue;
+        const drafted = values[descriptor.name];
+        if (!isRowDraftArray(drafted)) continue;
+        const rows = drafted;
+        const childType = descriptor.childType;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        instance[descriptor.name] = rows.map((row)=>reconstructChild(childType, row));
+    }
+}
+/**
+ * A member this function must not write.
+ *
+ * `readonly` is the declared half — `describeEntityColumns` keeps read-only
+ * members because a form still *shows* them, so unlike the column list this
+ * walk has to filter them itself, exactly as `buildEntityInstance` does.
+ *
+ * The relation half is checked twice on purpose. The declared `link` /
+ * `linkCollection` types are `applyEntityLinks`' business, and the runtime
+ * `instanceof` catches a bare `@accessor()` on a relation that declared no
+ * type: those accessors are getter-only, so assigning a coerced string to one
+ * would throw rather than misbehave quietly.
+ *
+ * `composition` is excluded for the reason `linkCollection` is: it has no
+ * editor yet, so a draft never holds its rows and writing one would mean
+ * writing `undefined` over the master's own lines on every save. The rows'
+ * write path lands with the detail control (#122). `scalarCollection` is *not*
+ * excluded — it is a scalar as far as this walk is concerned, because its
+ * comma-list draft coerces losslessly back to a `string[]`.
+ */ function isWritableScalar(descriptor, current) {
+    if (descriptor.readonly) return false;
+    if (descriptor.type === 'link' || descriptor.type === 'linkCollection' || descriptor.type === 'composition') {
+        return false;
+    }
+    return !(current instanceof EntityLink || current instanceof EntityCollectionLink);
+}
+/**
+ * Rebuilds a domain instance from a form's string draft, deriving every
+ * assignment from the entity's own accessor metadata.
+ *
+ * This is the one genuinely hand-written part of an entity form, and writing it
+ * per entity is a bug farm: each one repeats the same empty-string-to-undefined
+ * rule, and each one has to remember to carry back a member the form hides —
+ * `ProductBrand.code` is assigned by the create transaction, and dropping it
+ * blanks the record's identifier on every update. Deriving the walk from the
+ * metadata makes that structural instead of remembered.
+ *
+ * **Construction is zero-argument.** `new entityConstructor()` then assignment
+ * through setters, the same shape `buildEntityInstance` uses to rebuild a record
+ * off the wire. Entities default their constructor parameters, and a required
+ * member is filled by its setter a moment later — so required-ness stays one
+ * fact (the `@accessor({ required })` flag the form already validates against)
+ * rather than a second, unverifiable list of constructor argument names.
+ *
+ * Constructing first also gives `describeEntityColumns` a sample, which is what
+ * lets it infer `link`-ness for an accessor that declared no `type`: relations
+ * are initialized by the constructor, so the fresh instance already carries them.
+ *
+ * **`existing` supplies the id and nothing else.** Every other member comes from
+ * the draft, which was seeded from the record — so a create/update distinction
+ * lives here once instead of a `target.id = entity?.id` line per form. A draft
+ * may be client-supplied (a workspace autosaves it), which is not a new surface:
+ * a save route already overwrites the id from its own route parameter.
+ *
+ * Pure and framework-free, so the same reconstruction runs in a browser form and
+ * in a backend use-case assembling an entity from a raw draft.
+ */ export function reconstructEntity(entityConstructor, values, { existing, selection } = {}) {
+    const instance = new entityConstructor();
+    const descriptors = describeEntityColumns(entityConstructor, instance);
+    for (const descriptor of descriptors){
+        // The draft is keyed by accessor name, and so is the assignment: `key` is
+        // `alias ?? name`, which is the wire/SQL column, not the JS property.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const current = instance[descriptor.name];
+        if (!isWritableScalar(descriptor, current)) continue;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        instance[descriptor.name] = coerceFieldValue(descriptor, readDraftString(values, descriptor.name));
+    }
+    applyEntityComposition(instance, descriptors, values);
+    applyEntityLinks(instance, descriptors, values, selection);
+    if (existing !== undefined) instance.id = existing.id;
+    return instance;
+}
+
+//# sourceMappingURL=reconstruct-entity.js.map

package/dist/entity-definition/reconstruct/reconstruct-entity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/reconstruct/reconstruct-entity.ts"],"sourcesContent":["import { Entity, EntityConstructor } from '../../types/Entity.js';\nimport { EntityDraft, readDraftString } from '../../types/EntityDraft.js';\nimport { isRowDraftArray } from '../../types/EntityRowDraft.js';\nimport {\n  describeEntityColumns,\n  EntityFieldDescriptor,\n} from '../describe/index.js';\nimport {\n  applyEntityLinks,\n  type EntityLinkSelection,\n} from '../links/apply-entity-links/index.js';\nimport { EntityCollectionLink } from '../links/entity-collection-link/index.js';\nimport { EntityLink } from '../links/entity-link/index.js';\nimport { coerceFieldValue } from './coerce-field-value.js';\nimport { reconstructChild } from './reconstruct-child.js';\n\n/** Everything {@link reconstructEntity} needs beyond the draft itself. */\nexport interface ReconstructEntityOptions<TEntity extends Entity> {\n  /**\n   * The record being edited. Supplies the `id` and nothing else — see\n   * {@link reconstructEntity} on why it is only the id.\n   */\n  existing?: TEntity;\n  /**\n   * The instances a picker handed over, for members whose declared\n   * `linkSerialization` is `embedded`. Passed straight to `applyEntityLinks`.\n   */\n  selection?: EntityLinkSelection;\n}\n\n/**\n * Writes an entity's owned collections back from the rows its draft holds.\n *\n * A **second pass** rather than a branch inside the scalar walk, and the reason\n * is the invariant it protects: `isWritableScalar` must go on refusing\n * `composition`, because assigning a coerced string to a member that holds rows\n * is how the master's own lines get blanked on a save that touches nothing else.\n * Keeping the two walks separate means a `composition` is written by exactly one\n * piece of code, and that code cannot be reached with a string.\n *\n * A member whose draft entry is missing or unreadable is **skipped, not\n * cleared** — the same rule the scalar walk applies to a member the form hides.\n * A draft written before this member existed, or one restored from a build that\n * did not know it, must leave the record's rows exactly as they were rather than\n * emptying them, which is a data loss the user never asked for and cannot see.\n * An explicitly empty list *is* a value and is written: that is a user who\n * removed every row.\n *\n * Read-only is honoured for the same reason as everywhere else, and the\n * `childType` guard is not defensive — a `composition` that declared no child\n * has no columns to coerce against, so there is nothing to rebuild.\n */\nfunction applyEntityComposition(\n  instance: object,\n  descriptors: readonly EntityFieldDescriptor[],\n  values: EntityDraft,\n): void {\n  for (const descriptor of descriptors) {\n    if (descriptor.type !== 'composition') continue;\n    if (descriptor.readonly || descriptor.childType === undefined) continue;\n\n    const drafted = values[descriptor.name];\n    if (!isRowDraftArray(drafted)) continue;\n\n    const rows = drafted;\n    const childType = descriptor.childType;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (instance as any)[descriptor.name] = rows.map(row =>\n      reconstructChild(childType, row),\n    );\n  }\n}\n\n/**\n * A member this function must not write.\n *\n * `readonly` is the declared half — `describeEntityColumns` keeps read-only\n * members because a form still *shows* them, so unlike the column list this\n * walk has to filter them itself, exactly as `buildEntityInstance` does.\n *\n * The relation half is checked twice on purpose. The declared `link` /\n * `linkCollection` types are `applyEntityLinks`' business, and the runtime\n * `instanceof` catches a bare `@accessor()` on a relation that declared no\n * type: those accessors are getter-only, so assigning a coerced string to one\n * would throw rather than misbehave quietly.\n *\n * `composition` is excluded for the reason `linkCollection` is: it has no\n * editor yet, so a draft never holds its rows and writing one would mean\n * writing `undefined` over the master's own lines on every save. The rows'\n * write path lands with the detail control (#122). `scalarCollection` is *not*\n * excluded — it is a scalar as far as this walk is concerned, because its\n * comma-list draft coerces losslessly back to a `string[]`.\n */\nfunction isWritableScalar(\n  descriptor: EntityFieldDescriptor,\n  current: unknown,\n): boolean {\n  if (descriptor.readonly) return false;\n  if (\n    descriptor.type === 'link' ||\n    descriptor.type === 'linkCollection' ||\n    descriptor.type === 'composition'\n  ) {\n    return false;\n  }\n  return !(\n    current instanceof EntityLink || current instanceof EntityCollectionLink\n  );\n}\n\n/**\n * Rebuilds a domain instance from a form's string draft, deriving every\n * assignment from the entity's own accessor metadata.\n *\n * This is the one genuinely hand-written part of an entity form, and writing it\n * per entity is a bug farm: each one repeats the same empty-string-to-undefined\n * rule, and each one has to remember to carry back a member the form hides —\n * `ProductBrand.code` is assigned by the create transaction, and dropping it\n * blanks the record's identifier on every update. Deriving the walk from the\n * metadata makes that structural instead of remembered.\n *\n * **Construction is zero-argument.** `new entityConstructor()` then assignment\n * through setters, the same shape `buildEntityInstance` uses to rebuild a record\n * off the wire. Entities default their constructor parameters, and a required\n * member is filled by its setter a moment later — so required-ness stays one\n * fact (the `@accessor({ required })` flag the form already validates against)\n * rather than a second, unverifiable list of constructor argument names.\n *\n * Constructing first also gives `describeEntityColumns` a sample, which is what\n * lets it infer `link`-ness for an accessor that declared no `type`: relations\n * are initialized by the constructor, so the fresh instance already carries them.\n *\n * **`existing` supplies the id and nothing else.** Every other member comes from\n * the draft, which was seeded from the record — so a create/update distinction\n * lives here once instead of a `target.id = entity?.id` line per form. A draft\n * may be client-supplied (a workspace autosaves it), which is not a new surface:\n * a save route already overwrites the id from its own route parameter.\n *\n * Pure and framework-free, so the same reconstruction runs in a browser form and\n * in a backend use-case assembling an entity from a raw draft.\n */\nexport function reconstructEntity<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  values: EntityDraft,\n  { existing, selection }: ReconstructEntityOptions<TEntity> = {},\n): TEntity {\n  const instance = new entityConstructor();\n  const descriptors = describeEntityColumns(entityConstructor, instance);\n\n  for (const descriptor of descriptors) {\n    // The draft is keyed by accessor name, and so is the assignment: `key` is\n    // `alias ?? name`, which is the wire/SQL column, not the JS property.\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const current = (instance as any)[descriptor.name];\n    if (!isWritableScalar(descriptor, current)) continue;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (instance as any)[descriptor.name] = coerceFieldValue(\n      descriptor,\n      readDraftString(values, descriptor.name),\n    );\n  }\n\n  applyEntityComposition(instance, descriptors, values);\n  applyEntityLinks(instance, descriptors, values, selection);\n\n  if (existing !== undefined) instance.id = existing.id;\n\n  return instance;\n}\n"],"names":["readDraftString","isRowDraftArray","describeEntityColumns","applyEntityLinks","EntityCollectionLink","EntityLink","coerceFieldValue","reconstructChild","applyEntityComposition","instance","descriptors","values","descriptor","type","readonly","childType","undefined","drafted","name","rows","map","row","isWritableScalar","current","reconstructEntity","entityConstructor","existing","selection","id"],"mappings":"AACA,SAAsBA,eAAe,QAAQ,6BAA6B;AAC1E,SAASC,eAAe,QAAQ,gCAAgC;AAChE,SACEC,qBAAqB,QAEhB,uBAAuB;AAC9B,SACEC,gBAAgB,QAEX,uCAAuC;AAC9C,SAASC,oBAAoB,QAAQ,2CAA2C;AAChF,SAASC,UAAU,QAAQ,gCAAgC;AAC3D,SAASC,gBAAgB,QAAQ,0BAA0B;AAC3D,SAASC,gBAAgB,QAAQ,yBAAyB;AAgB1D;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,SAASC,uBACPC,QAAgB,EAChBC,WAA6C,EAC7CC,MAAmB;IAEnB,KAAK,MAAMC,cAAcF,YAAa;QACpC,IAAIE,WAAWC,IAAI,KAAK,eAAe;QACvC,IAAID,WAAWE,QAAQ,IAAIF,WAAWG,SAAS,KAAKC,WAAW;QAE/D,MAAMC,UAAUN,MAAM,CAACC,WAAWM,IAAI,CAAC;QACvC,IAAI,CAACjB,gBAAgBgB,UAAU;QAE/B,MAAME,OAAOF;QACb,MAAMF,YAAYH,WAAWG,SAAS;QAEtC,8DAA8D;QAC7DN,QAAgB,CAACG,WAAWM,IAAI,CAAC,GAAGC,KAAKC,GAAG,CAACC,CAAAA,MAC5Cd,iBAAiBQ,WAAWM;IAEhC;AACF;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,SAASC,iBACPV,UAAiC,EACjCW,OAAgB;IAEhB,IAAIX,WAAWE,QAAQ,EAAE,OAAO;IAChC,IACEF,WAAWC,IAAI,KAAK,UACpBD,WAAWC,IAAI,KAAK,oBACpBD,WAAWC,IAAI,KAAK,eACpB;QACA,OAAO;IACT;IACA,OAAO,CACLU,CAAAA,mBAAmBlB,cAAckB,mBAAmBnB,oBAAmB;AAE3E;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASoB,kBACdC,iBAA6C,EAC7Cd,MAAmB,EACnB,EAAEe,QAAQ,EAAEC,SAAS,EAAqC,GAAG,CAAC,CAAC;IAE/D,MAAMlB,WAAW,IAAIgB;IACrB,MAAMf,cAAcR,sBAAsBuB,mBAAmBhB;IAE7D,KAAK,MAAMG,cAAcF,YAAa;QACpC,0EAA0E;QAC1E,sEAAsE;QACtE,8DAA8D;QAC9D,MAAMa,UAAU,AAACd,QAAgB,CAACG,WAAWM,IAAI,CAAC;QAClD,IAAI,CAACI,iBAAiBV,YAAYW,UAAU;QAE5C,8DAA8D;QAC7Dd,QAAgB,CAACG,WAAWM,IAAI,CAAC,GAAGZ,iBACnCM,YACAZ,gBAAgBW,QAAQC,WAAWM,IAAI;IAE3C;IAEAV,uBAAuBC,UAAUC,aAAaC;IAC9CR,iBAAiBM,UAAUC,aAAaC,QAAQgB;IAEhD,IAAID,aAAaV,WAAWP,SAASmB,EAAE,GAAGF,SAASE,EAAE;IAErD,OAAOnB;AACT"}

package/dist/entity-definition/serializer/deserialize.d.ts

@@ -0,0 +1,13 @@
+import { Effect } from 'effect';
+import { EntifixBuildError } from '../../base-entities/entifix-error/index.js';
+import { Entity, EntityConstructor } from '../../types/Entity.js';
+/**
+ * Result of deserializing a value against an entity constructor. A value can be
+ * a single entity, a missing entity (`undefined`) or an arbitrarily nested
+ * array of those — which lets collections recurse into arrays of arrays.
+ */
+type DeserializedEntity<TEntity extends Entity> = TEntity | undefined | DeserializedEntity<TEntity>[];
+export declare const deserializeSingleEntity: <TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, entityData: unknown) => Effect.Effect<TEntity | undefined, EntifixBuildError, never>;
+export declare const deserializeEntityCollection: <TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, entityCollectionData: unknown, failOnNull?: boolean) => Effect.Effect<DeserializedEntity<TEntity>[], EntifixBuildError, never>;
+export {};
+//# sourceMappingURL=deserialize.d.ts.map

package/dist/entity-definition/serializer/deserialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/serializer/deserialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAY,MAAM,uBAAuB,CAAC;AAK5E;;;;GAIG;AACH,KAAK,kBAAkB,CAAC,OAAO,SAAS,MAAM,IAC5C,OAAO,GAAG,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;AA+MtD,eAAO,MAAM,uBAAuB,GAAI,OAAO,SAAS,MAAM,EAC5D,mBAAmB,iBAAiB,CAAC,OAAO,CAAC,EAC7C,YAAY,OAAO,iEAWjB,CAAC;AAEL,eAAO,MAAM,2BAA2B,GAAI,OAAO,SAAS,MAAM,EAChE,mBAAmB,iBAAiB,CAAC,OAAO,CAAC,EAC7C,sBAAsB,OAAO,EAC7B,oBAAkB,2EAgBhB,CAAC"}