@entifix/core 0.1.0-0

package/dist/rsql/sort-param.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/rsql/sort-param.ts"],"sourcesContent":["import { EntifixBuildError } from '../base-entities/entifix-error/index.js';\nimport type { Entity, EntityConstructor } from '../types/Entity.js';\nimport type { EntitySorting, EntitySortType } from '../types/EntitySorting.js';\nimport { allowedDescriptors } from './coerce-rsql.js';\n\n/**\n * RSQL standardizes filtering only, so sorting travels in its own `sort`\n * parameter: `+name,-code`. The sign is the direction (`-` descending, `+` or\n * none ascending) and the list position is the precedence — which is exactly\n * what `EntitySorting`'s numeric keys mean, so the two forms map one to one.\n */\nconst SEPARATOR = ',';\n\n/** Flattens the sorting records into `[property, direction]` in priority order. */\nfunction orderedEntries<TEntity extends Entity>(\n  sorting: EntitySorting<TEntity>[],\n): Array<[string, EntitySortType]> {\n  const entries: Array<[string, EntitySortType]> = [];\n\n  for (const record of sorting) {\n    for (const priority of Object.keys(record)\n      .map(Number)\n      .sort((left, right) => left - right)) {\n      const entry = record[priority];\n      if (entry) entries.push([String(entry.property), entry.type]);\n    }\n  }\n\n  return entries;\n}\n\n/**\n * Serializes an {@link EntityLoadRequest}'s `sorting` into the `sort`\n * parameter's value. Absent or empty sorting yields `''`, which callers omit\n * from the URL rather than sending empty.\n */\nexport function serializeSort<TEntity extends Entity>(\n  sorting?: EntitySorting<TEntity>[],\n): string {\n  if (!sorting || sorting.length === 0) return '';\n\n  return orderedEntries(sorting)\n    .map(([property, type]) => `${type === 'desc' ? '-' : '+'}${property}`)\n    .join(SEPARATOR);\n}\n\n/**\n * Parses the `sort` parameter into the request's `sorting`, allowlisting every\n * member against the entity's `sortable` metadata for the same reason\n * {@link coerceFiltering} does: an unchecked property name would let a client\n * sort by a member the entity never meant to expose, and an unindexed one is a\n * collection scan.\n *\n * Returns a single-record array — one record whose numeric keys carry the\n * precedence — or `undefined` when there is nothing to sort by.\n */\nexport function parseSort<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  parameter: string | null | undefined,\n): EntitySorting<TEntity>[] | undefined {\n  const text = parameter?.trim();\n  if (!text) return undefined;\n\n  const allowed = allowedDescriptors(\n    entityConstructor,\n    descriptor => descriptor.sortable,\n  );\n\n  const record = {} as EntitySorting<TEntity>;\n  let priority = 0;\n\n  for (const rawTerm of text.split(SEPARATOR)) {\n    const term = rawTerm.trim();\n    if (term === '') continue;\n\n    const type: EntitySortType = term.startsWith('-') ? 'desc' : 'asc';\n    const name = term.replace(/^[+-]/, '');\n    const descriptor = allowed.get(name);\n\n    if (!descriptor) {\n      throw new EntifixBuildError(\n        `\"${name}\" is not a sortable member`,\n        undefined,\n        { property: name },\n      );\n    }\n\n    record[priority++] = { property: descriptor.key as keyof TEntity, type };\n  }\n\n  return priority === 0 ? undefined : [record];\n}\n"],"names":["EntifixBuildError","allowedDescriptors","SEPARATOR","orderedEntries","sorting","entries","record","priority","Object","keys","map","Number","sort","left","right","entry","push","String","property","type","serializeSort","length","join","parseSort","entityConstructor","parameter","text","trim","undefined","allowed","descriptor","sortable","rawTerm","split","term","startsWith","name","replace","get","key"],"mappings":"AAAA,SAASA,iBAAiB,QAAQ,0CAA0C;AAG5E,SAASC,kBAAkB,QAAQ,mBAAmB;AAEtD;;;;;CAKC,GACD,MAAMC,YAAY;AAElB,iFAAiF,GACjF,SAASC,eACPC,OAAiC;IAEjC,MAAMC,UAA2C,EAAE;IAEnD,KAAK,MAAMC,UAAUF,QAAS;QAC5B,KAAK,MAAMG,YAAYC,OAAOC,IAAI,CAACH,QAChCI,GAAG,CAACC,QACJC,IAAI,CAAC,CAACC,MAAMC,QAAUD,OAAOC,OAAQ;YACtC,MAAMC,QAAQT,MAAM,CAACC,SAAS;YAC9B,IAAIQ,OAAOV,QAAQW,IAAI,CAAC;gBAACC,OAAOF,MAAMG,QAAQ;gBAAGH,MAAMI,IAAI;aAAC;QAC9D;IACF;IAEA,OAAOd;AACT;AAEA;;;;CAIC,GACD,OAAO,SAASe,cACdhB,OAAkC;IAElC,IAAI,CAACA,WAAWA,QAAQiB,MAAM,KAAK,GAAG,OAAO;IAE7C,OAAOlB,eAAeC,SACnBM,GAAG,CAAC,CAAC,CAACQ,UAAUC,KAAK,GAAK,GAAGA,SAAS,SAAS,MAAM,MAAMD,UAAU,EACrEI,IAAI,CAACpB;AACV;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASqB,UACdC,iBAA6C,EAC7CC,SAAoC;IAEpC,MAAMC,OAAOD,6BAAAA,UAAWE,IAAI;IAC5B,IAAI,CAACD,MAAM,OAAOE;IAElB,MAAMC,UAAU5B,mBACduB,mBACAM,CAAAA,aAAcA,WAAWC,QAAQ;IAGnC,MAAMzB,SAAS,CAAC;IAChB,IAAIC,WAAW;IAEf,KAAK,MAAMyB,WAAWN,KAAKO,KAAK,CAAC/B,WAAY;QAC3C,MAAMgC,OAAOF,QAAQL,IAAI;QACzB,IAAIO,SAAS,IAAI;QAEjB,MAAMf,OAAuBe,KAAKC,UAAU,CAAC,OAAO,SAAS;QAC7D,MAAMC,OAAOF,KAAKG,OAAO,CAAC,SAAS;QACnC,MAAMP,aAAaD,QAAQS,GAAG,CAACF;QAE/B,IAAI,CAACN,YAAY;YACf,MAAM,IAAI9B,kBACR,CAAC,CAAC,EAAEoC,KAAK,0BAA0B,CAAC,EACpCR,WACA;gBAAEV,UAAUkB;YAAK;QAErB;QAEA9B,MAAM,CAACC,WAAW,GAAG;YAAEW,UAAUY,WAAWS,GAAG;YAAmBpB;QAAK;IACzE;IAEA,OAAOZ,aAAa,IAAIqB,YAAY;QAACtB;KAAO;AAC9C"}

package/dist/types/BulkOutcome.d.ts

@@ -0,0 +1,27 @@
+import type { EntityId } from './Entity.js';
+/**
+ * What happened to **one** row of a bulk action.
+ *
+ * Partial failure is the normal case, not an edge one: 40 rows selected, 3
+ * refused. A single success/failure result for the whole run lies in both
+ * directions — reported as a failure it hides the 37 that were written, and
+ * reported as a success it hides the 3 that were not, which is the worse half
+ * because the user walks away believing the work is done.
+ *
+ * `code` is an **error code**, never a sentence. Services answer
+ * `{ error, code, detail }` and the browser renders the code through the
+ * `errors` catalog, so a failure reason stays translatable and a new one fails
+ * `@r10c/i18n-check` rather than reaching a user in English
+ * ([docs/I18N.md](../../../../../../docs/I18N.md)).
+ */
+export interface BulkOutcome {
+    id: EntityId;
+    ok: boolean;
+    /** Present only when `ok` is false. */
+    code?: string;
+}
+/** The ids that failed — what a retry re-runs, and nothing else. */
+export declare function failedIds(outcomes: readonly BulkOutcome[]): EntityId[];
+/** How many rows were written. */
+export declare function succeededCount(outcomes: readonly BulkOutcome[]): number;
+//# sourceMappingURL=BulkOutcome.d.ts.map

package/dist/types/BulkOutcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulkOutcome.d.ts","sourceRoot":"","sources":["../../src/types/BulkOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,QAAQ,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,QAAQ,EAAE,CAEtE;AAED,kCAAkC;AAClC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAEvE"}

package/dist/types/BulkOutcome.js

@@ -0,0 +1,8 @@
+/** The ids that failed — what a retry re-runs, and nothing else. */ export function failedIds(outcomes) {
+    return outcomes.filter((outcome)=>!outcome.ok).map((outcome)=>outcome.id);
+}
+/** How many rows were written. */ export function succeededCount(outcomes) {
+    return outcomes.filter((outcome)=>outcome.ok).length;
+}
+
+//# sourceMappingURL=BulkOutcome.js.map

package/dist/types/BulkOutcome.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/BulkOutcome.ts"],"sourcesContent":["import type { EntityId } from './Entity.js';\n\n/**\n * What happened to **one** row of a bulk action.\n *\n * Partial failure is the normal case, not an edge one: 40 rows selected, 3\n * refused. A single success/failure result for the whole run lies in both\n * directions — reported as a failure it hides the 37 that were written, and\n * reported as a success it hides the 3 that were not, which is the worse half\n * because the user walks away believing the work is done.\n *\n * `code` is an **error code**, never a sentence. Services answer\n * `{ error, code, detail }` and the browser renders the code through the\n * `errors` catalog, so a failure reason stays translatable and a new one fails\n * `@r10c/i18n-check` rather than reaching a user in English\n * ([docs/I18N.md](../../../../../../docs/I18N.md)).\n */\nexport interface BulkOutcome {\n  id: EntityId;\n  ok: boolean;\n  /** Present only when `ok` is false. */\n  code?: string;\n}\n\n/** The ids that failed — what a retry re-runs, and nothing else. */\nexport function failedIds(outcomes: readonly BulkOutcome[]): EntityId[] {\n  return outcomes.filter(outcome => !outcome.ok).map(outcome => outcome.id);\n}\n\n/** How many rows were written. */\nexport function succeededCount(outcomes: readonly BulkOutcome[]): number {\n  return outcomes.filter(outcome => outcome.ok).length;\n}\n"],"names":["failedIds","outcomes","filter","outcome","ok","map","id","succeededCount","length"],"mappings":"AAwBA,kEAAkE,GAClE,OAAO,SAASA,UAAUC,QAAgC;IACxD,OAAOA,SAASC,MAAM,CAACC,CAAAA,UAAW,CAACA,QAAQC,EAAE,EAAEC,GAAG,CAACF,CAAAA,UAAWA,QAAQG,EAAE;AAC1E;AAEA,gCAAgC,GAChC,OAAO,SAASC,eAAeN,QAAgC;IAC7D,OAAOA,SAASC,MAAM,CAACC,CAAAA,UAAWA,QAAQC,EAAE,EAAEI,MAAM;AACtD"}

package/dist/types/Entity.d.ts

@@ -0,0 +1,6 @@
+export type EntityId = string | number | symbol | undefined;
+export interface Entity {
+    id: EntityId;
+}
+export type EntityConstructor<TEntity extends Entity> = new (...args: any[]) => TEntity;
+//# sourceMappingURL=Entity.d.ts.map

package/dist/types/Entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../src/types/Entity.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,SAAS,MAAM,IAAI,KAItD,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,OAAO,CAAC"}

package/dist/types/Entity.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=Entity.js.map

package/dist/types/Entity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/Entity.ts"],"sourcesContent":["export type EntityId = string | number | symbol | undefined;\n\nexport interface Entity {\n  id: EntityId;\n}\n\nexport type EntityConstructor<TEntity extends Entity> = new (\n  // Allow any arguments in the constructor, as we don't know the specific parameters for each entity.\n  // The important part is that it returns an instance of TEntity.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ...args: any[]\n) => TEntity;\n"],"names":[],"mappings":"AAMA,WAKa"}

package/dist/types/EntityAction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a caller wants to do with a resource: the CRUD triple every entity has
+ * by construction, as opposed to a verb a domain declares with `@useCase()`.
+ *
+ * It lives in `core` rather than in the authorization vocabulary because two
+ * layers that may not import each other both need it. `@entifix/authz` owns
+ * the *permission* built from an action and re-exports these as `Actions` /
+ * `Action`; `@entifix/react-controls` reads the same triple off a served
+ * `EntityMetadataDocument` to decide whether to render Save and Delete, and
+ * `entifix:react` may not depend on the business layer
+ * ([ADR 0026](../../../../../../docs/adr/0026-the-use-case-descriptor-and-served-entity-metadata.md)).
+ */
+export declare const ENTITY_ACTIONS: readonly ["read", "write", "delete"];
+export type EntityAction = (typeof ENTITY_ACTIONS)[number];
+//# sourceMappingURL=EntityAction.d.ts.map

package/dist/types/EntityAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityAction.d.ts","sourceRoot":"","sources":["../../src/types/EntityAction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,sCAAuC,CAAC;AACnE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/types/EntityAction.js

@@ -0,0 +1,18 @@
+/**
+ * What a caller wants to do with a resource: the CRUD triple every entity has
+ * by construction, as opposed to a verb a domain declares with `@useCase()`.
+ *
+ * It lives in `core` rather than in the authorization vocabulary because two
+ * layers that may not import each other both need it. `@entifix/authz` owns
+ * the *permission* built from an action and re-exports these as `Actions` /
+ * `Action`; `@entifix/react-controls` reads the same triple off a served
+ * `EntityMetadataDocument` to decide whether to render Save and Delete, and
+ * `entifix:react` may not depend on the business layer
+ * ([ADR 0026](../../../../../../docs/adr/0026-the-use-case-descriptor-and-served-entity-metadata.md)).
+ */ export const ENTITY_ACTIONS = [
+    'read',
+    'write',
+    'delete'
+];
+
+//# sourceMappingURL=EntityAction.js.map

package/dist/types/EntityAction.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityAction.ts"],"sourcesContent":["/**\n * What a caller wants to do with a resource: the CRUD triple every entity has\n * by construction, as opposed to a verb a domain declares with `@useCase()`.\n *\n * It lives in `core` rather than in the authorization vocabulary because two\n * layers that may not import each other both need it. `@entifix/authz` owns\n * the *permission* built from an action and re-exports these as `Actions` /\n * `Action`; `@entifix/react-controls` reads the same triple off a served\n * `EntityMetadataDocument` to decide whether to render Save and Delete, and\n * `entifix:react` may not depend on the business layer\n * ([ADR 0026](../../../../../../docs/adr/0026-the-use-case-descriptor-and-served-entity-metadata.md)).\n */\nexport const ENTITY_ACTIONS = ['read', 'write', 'delete'] as const;\nexport type EntityAction = (typeof ENTITY_ACTIONS)[number];\n"],"names":["ENTITY_ACTIONS"],"mappings":"AAAA;;;;;;;;;;;CAWC,GACD,OAAO,MAAMA,iBAAiB;IAAC;IAAQ;IAAS;CAAS,CAAU"}

package/dist/types/EntityDraft.d.ts

@@ -0,0 +1,47 @@
+import type { EntityRowDraft } from './EntityRowDraft.js';
+/**
+ * A form's in-progress values, keyed by accessor name.
+ *
+ * A scalar member's value is a **string**, because that is what a native input
+ * round-trips: a `scalarCollection` drafts as a comma list, a `date` as
+ * `yyyy-mm-dd`, a relation as its foreign key. Reading one is therefore still
+ * `values[name] ?? ''` in every place that only edits scalars.
+ *
+ * A **`composition`** member's value is an `EntityRowDraft[]` — rows the master
+ * owns, each a string map carrying its own `ROW_KEY`. That is the whole reason
+ * this is a union and not `string`: rows have no lossless string form, and the
+ * two shapes a draft can hold are exactly the two ADR 0034 named.
+ *
+ * **Exactly two shapes, and the union says so rather than `JsonValue`.** Both
+ * are JSON — a workspace autosaves a draft through `createJSONStorage`
+ * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)),
+ * so a class instance, an `EntityLink` or a `Date` does not degrade, it returns
+ * as something else, silently — but `JsonValue` would say more than is true. A
+ * member whose value is neither a string nor a row list has no editor, no
+ * coercion and no restore rule: `reconstructEntity` would carry it through
+ * untouched and the serializer would write it.
+ *
+ * The narrower union is also what keeps the form engine compiling. `JsonValue`
+ * is **recursive**, and TanStack Form derives a field-path type from the value
+ * it is given, so a draft typed that way makes that derivation unbounded —
+ * `Type instantiation is excessively deep and possibly infinite`. A row is a
+ * flat string map, so this union has a bottom and the derivation terminates.
+ *
+ * The alias exists in **one** place on purpose. The same structural type was
+ * declared four times — `EntityFormValues`, `EntityFormDraft`, `EntityLinkDraft`
+ * and `EntityCrudDraft` — and collapsing them is what made this widening a
+ * single edit rather than four found by search.
+ */
+export type EntityDraftValue = string | readonly EntityRowDraft[];
+export type EntityDraft = Record<string, EntityDraftValue>;
+/**
+ * The string a draft holds for a scalar member.
+ *
+ * A draft value is `JsonValue` now, but every scalar editor still writes and
+ * reads a string, so this is the read every one of them performs — in one
+ * place, so a member that came back from storage as a number or `null` renders
+ * as an empty input instead of flipping React from controlled to uncontrolled
+ * mid-render.
+ */
+export declare function readDraftString(values: EntityDraft | undefined, name: string): string;
+//# sourceMappingURL=EntityDraft.d.ts.map

package/dist/types/EntityDraft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityDraft.d.ts","sourceRoot":"","sources":["../../src/types/EntityDraft.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,cAAc,EAAE,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,GACX,MAAM,CAGR"}

package/dist/types/EntityDraft.js

@@ -0,0 +1,14 @@
+/**
+ * The string a draft holds for a scalar member.
+ *
+ * A draft value is `JsonValue` now, but every scalar editor still writes and
+ * reads a string, so this is the read every one of them performs — in one
+ * place, so a member that came back from storage as a number or `null` renders
+ * as an empty input instead of flipping React from controlled to uncontrolled
+ * mid-render.
+ */ export function readDraftString(values, name) {
+    const value = values == null ? void 0 : values[name];
+    return typeof value === 'string' ? value : '';
+}
+
+//# sourceMappingURL=EntityDraft.js.map

package/dist/types/EntityDraft.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityDraft.ts"],"sourcesContent":["import type { EntityRowDraft } from './EntityRowDraft.js';\n\n/**\n * A form's in-progress values, keyed by accessor name.\n *\n * A scalar member's value is a **string**, because that is what a native input\n * round-trips: a `scalarCollection` drafts as a comma list, a `date` as\n * `yyyy-mm-dd`, a relation as its foreign key. Reading one is therefore still\n * `values[name] ?? ''` in every place that only edits scalars.\n *\n * A **`composition`** member's value is an `EntityRowDraft[]` — rows the master\n * owns, each a string map carrying its own `ROW_KEY`. That is the whole reason\n * this is a union and not `string`: rows have no lossless string form, and the\n * two shapes a draft can hold are exactly the two ADR 0034 named.\n *\n * **Exactly two shapes, and the union says so rather than `JsonValue`.** Both\n * are JSON — a workspace autosaves a draft through `createJSONStorage`\n * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)),\n * so a class instance, an `EntityLink` or a `Date` does not degrade, it returns\n * as something else, silently — but `JsonValue` would say more than is true. A\n * member whose value is neither a string nor a row list has no editor, no\n * coercion and no restore rule: `reconstructEntity` would carry it through\n * untouched and the serializer would write it.\n *\n * The narrower union is also what keeps the form engine compiling. `JsonValue`\n * is **recursive**, and TanStack Form derives a field-path type from the value\n * it is given, so a draft typed that way makes that derivation unbounded —\n * `Type instantiation is excessively deep and possibly infinite`. A row is a\n * flat string map, so this union has a bottom and the derivation terminates.\n *\n * The alias exists in **one** place on purpose. The same structural type was\n * declared four times — `EntityFormValues`, `EntityFormDraft`, `EntityLinkDraft`\n * and `EntityCrudDraft` — and collapsing them is what made this widening a\n * single edit rather than four found by search.\n */\nexport type EntityDraftValue = string | readonly EntityRowDraft[];\n\nexport type EntityDraft = Record<string, EntityDraftValue>;\n\n/**\n * The string a draft holds for a scalar member.\n *\n * A draft value is `JsonValue` now, but every scalar editor still writes and\n * reads a string, so this is the read every one of them performs — in one\n * place, so a member that came back from storage as a number or `null` renders\n * as an empty input instead of flipping React from controlled to uncontrolled\n * mid-render.\n */\nexport function readDraftString(\n  values: EntityDraft | undefined,\n  name: string,\n): string {\n  const value = values?.[name];\n  return typeof value === 'string' ? value : '';\n}\n"],"names":["readDraftString","values","name","value"],"mappings":"AAuCA;;;;;;;;CAQC,GACD,OAAO,SAASA,gBACdC,MAA+B,EAC/BC,IAAY;IAEZ,MAAMC,QAAQF,0BAAAA,MAAQ,CAACC,KAAK;IAC5B,OAAO,OAAOC,UAAU,WAAWA,QAAQ;AAC7C"}

package/dist/types/EntityFiltering.d.ts

@@ -0,0 +1,45 @@
+import type { Entity } from './Entity.js';
+export declare const EntityFilterBinaryOperators: readonly ["eq", "ne", "gt", "gte", "lt", "lte"];
+export type EntityFilterBinaryOperator = (typeof EntityFilterBinaryOperators)[number];
+export type EntityFilterBinary<TEntity extends Entity, TKey extends keyof TEntity> = {
+    property: TKey;
+    operator: EntityFilterBinaryOperator;
+    value: TEntity[TKey];
+};
+export declare const EntityFilterArrayOperators: readonly ["in", "nin"];
+export type EntityFilterArrayOperator = (typeof EntityFilterArrayOperators)[number];
+export type EntityFilterArray<TEntity extends Entity, TKey extends keyof TEntity> = {
+    property: TKey;
+    operator: EntityFilterArrayOperator;
+    values: Array<TEntity[TKey]>;
+};
+export declare const EntityFilterRangeOperators: readonly ["between", "nbetween"];
+export type EntityFilterRangeOperator = (typeof EntityFilterRangeOperators)[number];
+export type EntityFilterRange<TEntity extends Entity, TKey extends keyof TEntity> = {
+    property: TKey;
+    operator: EntityFilterRangeOperator;
+    start: TEntity[TKey];
+    end: TEntity[TKey];
+};
+export declare const EntityFilterStringOperators: readonly ["like", "nlike"];
+export type EntityFilterStringOperator = (typeof EntityFilterStringOperators)[number];
+export type EntityFilterString<TEntity extends Entity> = {
+    property: keyof TEntity;
+    operator: EntityFilterStringOperator;
+    value: string;
+};
+export declare const EntityFilterNullOperators: readonly ["isNull", "isNotNull"];
+export type EntityFilterNullOperator = (typeof EntityFilterNullOperators)[number];
+export type EntityFilterNull<TEntity extends Entity, TKey extends keyof TEntity> = {
+    property: TKey;
+    operator: EntityFilterNullOperator;
+};
+export type EntityFilter<TEntity extends Entity> = EntityFilterBinary<TEntity, keyof TEntity> | EntityFilterArray<TEntity, keyof TEntity> | EntityFilterRange<TEntity, keyof TEntity> | EntityFilterString<TEntity> | EntityFilterNull<TEntity, keyof TEntity>;
+export declare const LogicOperators: readonly ["and", "or"];
+export type LogicOperator = (typeof LogicOperators)[number];
+export type FilterGroup<TEntity extends Entity> = {
+    operator: LogicOperator;
+    values: Array<EntityFilter<TEntity> | FilterGroup<TEntity>>;
+};
+export type EntityFiltering<TEntity extends Entity> = EntityFilter<TEntity> | Array<EntityFilter<TEntity>> | FilterGroup<TEntity>;
+//# sourceMappingURL=EntityFiltering.d.ts.map

package/dist/types/EntityFiltering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityFiltering.d.ts","sourceRoot":"","sources":["../../src/types/EntityFiltering.ts"],"names":[],"mappings":"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"}

package/dist/types/EntityFiltering.js

@@ -0,0 +1,30 @@
+export const EntityFilterBinaryOperators = [
+    'eq',
+    'ne',
+    'gt',
+    'gte',
+    'lt',
+    'lte'
+];
+export const EntityFilterArrayOperators = [
+    'in',
+    'nin'
+];
+export const EntityFilterRangeOperators = [
+    'between',
+    'nbetween'
+];
+export const EntityFilterStringOperators = [
+    'like',
+    'nlike'
+];
+export const EntityFilterNullOperators = [
+    'isNull',
+    'isNotNull'
+];
+export const LogicOperators = [
+    'and',
+    'or'
+];
+
+//# sourceMappingURL=EntityFiltering.js.map

package/dist/types/EntityFiltering.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityFiltering.ts"],"sourcesContent":["import type { Entity } from './Entity.js';\n\nexport const EntityFilterBinaryOperators = [\n  'eq',\n  'ne',\n  'gt',\n  'gte',\n  'lt',\n  'lte',\n] as const;\nexport type EntityFilterBinaryOperator =\n  (typeof EntityFilterBinaryOperators)[number];\nexport type EntityFilterBinary<\n  TEntity extends Entity,\n  TKey extends keyof TEntity,\n> = {\n  property: TKey;\n  operator: EntityFilterBinaryOperator;\n  value: TEntity[TKey];\n};\n\nexport const EntityFilterArrayOperators = ['in', 'nin'] as const;\nexport type EntityFilterArrayOperator =\n  (typeof EntityFilterArrayOperators)[number];\nexport type EntityFilterArray<\n  TEntity extends Entity,\n  TKey extends keyof TEntity,\n> = {\n  property: TKey;\n  operator: EntityFilterArrayOperator;\n  values: Array<TEntity[TKey]>;\n};\n\nexport const EntityFilterRangeOperators = ['between', 'nbetween'] as const;\nexport type EntityFilterRangeOperator =\n  (typeof EntityFilterRangeOperators)[number];\nexport type EntityFilterRange<\n  TEntity extends Entity,\n  TKey extends keyof TEntity,\n> = {\n  property: TKey;\n  operator: EntityFilterRangeOperator;\n  start: TEntity[TKey];\n  end: TEntity[TKey];\n};\n\nexport const EntityFilterStringOperators = ['like', 'nlike'] as const;\nexport type EntityFilterStringOperator =\n  (typeof EntityFilterStringOperators)[number];\nexport type EntityFilterString<TEntity extends Entity> = {\n  property: keyof TEntity;\n  operator: EntityFilterStringOperator;\n  value: string;\n};\n\nexport const EntityFilterNullOperators = ['isNull', 'isNotNull'] as const;\nexport type EntityFilterNullOperator =\n  (typeof EntityFilterNullOperators)[number];\nexport type EntityFilterNull<\n  TEntity extends Entity,\n  TKey extends keyof TEntity,\n> = {\n  property: TKey;\n  operator: EntityFilterNullOperator;\n};\n\nexport type EntityFilter<TEntity extends Entity> =\n  | EntityFilterBinary<TEntity, keyof TEntity>\n  | EntityFilterArray<TEntity, keyof TEntity>\n  | EntityFilterRange<TEntity, keyof TEntity>\n  | EntityFilterString<TEntity>\n  | EntityFilterNull<TEntity, keyof TEntity>;\n\nexport const LogicOperators = ['and', 'or'] as const;\nexport type LogicOperator = (typeof LogicOperators)[number];\nexport type FilterGroup<TEntity extends Entity> = {\n  operator: LogicOperator;\n  values: Array<EntityFilter<TEntity> | FilterGroup<TEntity>>;\n};\n\nexport type EntityFiltering<TEntity extends Entity> =\n  EntityFilter<TEntity> | Array<EntityFilter<TEntity>> | FilterGroup<TEntity>;\n"],"names":["EntityFilterBinaryOperators","EntityFilterArrayOperators","EntityFilterRangeOperators","EntityFilterStringOperators","EntityFilterNullOperators","LogicOperators"],"mappings":"AAEA,OAAO,MAAMA,8BAA8B;IACzC;IACA;IACA;IACA;IACA;IACA;CACD,CAAU;AAYX,OAAO,MAAMC,6BAA6B;IAAC;IAAM;CAAM,CAAU;AAYjE,OAAO,MAAMC,6BAA6B;IAAC;IAAW;CAAW,CAAU;AAa3E,OAAO,MAAMC,8BAA8B;IAAC;IAAQ;CAAQ,CAAU;AAStE,OAAO,MAAMC,4BAA4B;IAAC;IAAU;CAAY,CAAU;AAkB1E,OAAO,MAAMC,iBAAiB;IAAC;IAAO;CAAK,CAAU"}

package/dist/types/EntityLoadRequest.d.ts

@@ -0,0 +1,10 @@
+import type { Entity } from './Entity.js';
+import type { EntityFiltering } from './EntityFiltering.js';
+import type { EntitySorting } from './EntitySorting.js';
+export interface EntityLoadRequest<TEntity extends Entity = Entity> {
+    filtering?: EntityFiltering<TEntity>[];
+    sorting?: EntitySorting<TEntity>[];
+    page?: number;
+    pageSize?: number;
+}
+//# sourceMappingURL=EntityLoadRequest.d.ts.map

package/dist/types/EntityLoadRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityLoadRequest.d.ts","sourceRoot":"","sources":["../../src/types/EntityLoadRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAChE,SAAS,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;IACvC,OAAO,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types/EntityLoadRequest.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=EntityLoadRequest.js.map

package/dist/types/EntityLoadRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityLoadRequest.ts"],"sourcesContent":["import type { Entity } from './Entity.js';\nimport type { EntityFiltering } from './EntityFiltering.js';\nimport type { EntitySorting } from './EntitySorting.js';\n\nexport interface EntityLoadRequest<TEntity extends Entity = Entity> {\n  filtering?: EntityFiltering<TEntity>[];\n  sorting?: EntitySorting<TEntity>[];\n  page?: number;\n  pageSize?: number;\n}\n"],"names":[],"mappings":"AAIA,WAKC"}

package/dist/types/EntityPage.d.ts

@@ -0,0 +1,8 @@
+import type { Entity } from './Entity.js';
+import type { EntityLoadRequest } from './EntityLoadRequest.js';
+export interface EntityPage<TEntity extends Entity> {
+    items: TEntity[];
+    total: number;
+    request: EntityLoadRequest<TEntity>;
+}
+//# sourceMappingURL=EntityPage.d.ts.map

package/dist/types/EntityPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityPage.d.ts","sourceRoot":"","sources":["../../src/types/EntityPage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,UAAU,CAAC,OAAO,SAAS,MAAM;IAChD,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;CACrC"}

package/dist/types/EntityPage.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=EntityPage.js.map

package/dist/types/EntityPage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityPage.ts"],"sourcesContent":["import type { Entity } from './Entity.js';\nimport type { EntityLoadRequest } from './EntityLoadRequest.js';\n\nexport interface EntityPage<TEntity extends Entity> {\n  items: TEntity[];\n  total: number;\n  request: EntityLoadRequest<TEntity>;\n}\n"],"names":[],"mappings":"AAGA,WAIC"}

package/dist/types/EntityRowDraft.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The member a row draft carries its client-side identity in.
+ *
+ * A `composition`'s rows are editable before the record they belong to has ever
+ * been saved, and the child is a **value** — `OrderItem` has no `id`, no domain
+ * and no permission namespace
+ * ([ADR 0034](../../../../../../docs/adr/0034-composition-metadata.md)). So the
+ * only identity a row can have is one the browser mints, and it exists for
+ * exactly two jobs: a stable React key, and stable focus across a re-render.
+ *
+ * `$` is not a legal first character for any member this repo declares, but that
+ * is a convention rather than a rule, so `describeChildColumns` **throws** on a
+ * child that declares this name instead of trusting it. A silent collision would
+ * be a row whose key is overwritten by its own data — it would re-key on every
+ * keystroke, lose focus mid-word, and address the wrong row's errors.
+ */
+export declare const ROW_KEY = "$key";
+/**
+ * One row of an owned collection, as a form holds it.
+ *
+ * Members are strings for the reason every draft value is a string — that is
+ * what a native input round-trips — and the whole row is JSON, because the
+ * workspace autosaves the master's draft through `createJSONStorage`
+ * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).
+ * The key rides **inside** the row rather than in a parallel array precisely so
+ * that it survives that round trip attached to the row it identifies; a parallel
+ * structure re-introduces the index identity this exists to avoid.
+ *
+ * {@link ROW_KEY} never reaches the wire: `reconstructChild` drops it when it
+ * rebuilds the child, so the serializer never sees a member the entity does not
+ * declare.
+ */
+export type EntityRowDraft = {
+    [member: string]: string;
+};
+/**
+ * Mints a key for a row the user has just added.
+ *
+ * `crypto.randomUUID` rather than a counter, because two drafts restored into
+ * one session must not collide, and a counter that resets on reload would
+ * re-issue keys a persisted draft is still using.
+ */
+export declare function newRowKey(): string;
+/**
+ * The key of the *n*th row as the record supplied it.
+ *
+ * Deterministic, and that is load-bearing rather than tidy. Seeding is not a
+ * one-time event: `useEntityForm` re-seeds whenever its `entity` changes
+ * identity, and a caller that builds the record inline re-seeds on **every
+ * render**. Minting a fresh random key there produces a draft that differs from
+ * the last one on every pass, so the form engine sees its defaults change
+ * forever and React stops with `Maximum update depth exceeded` — a live hang,
+ * not a test artifact.
+ *
+ * Positional is safe *here* precisely because it describes the record rather
+ * than the live list: re-seeding the same record yields the same keys, and once
+ * the user adds or removes anything the keys already in the draft are carried
+ * through untouched. A row added at runtime takes a {@link newRowKey} instead,
+ * which can never collide with this shape.
+ */
+export declare function seededRowKey(index: number): string;
+/**
+ * Whether a draft value is a usable list of rows.
+ *
+ * A restored draft is `JsonValue`, so a composition member can come back as
+ * anything — a string written by a build before this existed, `null`, or an
+ * array of the wrong shape. Every caller must ask before reading, and the answer
+ * for a value that fails is an empty grid rather than a crash: an unreadable
+ * draft is an unfinished edit, and `restoreEntityDraft` already discards those
+ * per entry rather than losing the whole form.
+ *
+ * A row missing its {@link ROW_KEY} fails, deliberately. Minting one here would
+ * hide the case where a row was written by something that does not know the
+ * contract, and the missing key would then be minted afresh on every render.
+ */
+export declare function isRowDraftArray(value: unknown): value is EntityRowDraft[];
+/** The rows a draft value holds, or an empty list when it holds none usable. */
+export declare function readRowDrafts(value: unknown): EntityRowDraft[];
+//# sourceMappingURL=EntityRowDraft.d.ts.map

package/dist/types/EntityRowDraft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityRowDraft.d.ts","sourceRoot":"","sources":["../../src/types/EntityRowDraft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,SAAS,CAAC;AAE9B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,EAAE,CAczE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,EAAE,CAE9D"}

package/dist/types/EntityRowDraft.js

@@ -0,0 +1,65 @@
+/**
+ * The member a row draft carries its client-side identity in.
+ *
+ * A `composition`'s rows are editable before the record they belong to has ever
+ * been saved, and the child is a **value** — `OrderItem` has no `id`, no domain
+ * and no permission namespace
+ * ([ADR 0034](../../../../../../docs/adr/0034-composition-metadata.md)). So the
+ * only identity a row can have is one the browser mints, and it exists for
+ * exactly two jobs: a stable React key, and stable focus across a re-render.
+ *
+ * `$` is not a legal first character for any member this repo declares, but that
+ * is a convention rather than a rule, so `describeChildColumns` **throws** on a
+ * child that declares this name instead of trusting it. A silent collision would
+ * be a row whose key is overwritten by its own data — it would re-key on every
+ * keystroke, lose focus mid-word, and address the wrong row's errors.
+ */ export const ROW_KEY = '$key';
+/**
+ * Mints a key for a row the user has just added.
+ *
+ * `crypto.randomUUID` rather than a counter, because two drafts restored into
+ * one session must not collide, and a counter that resets on reload would
+ * re-issue keys a persisted draft is still using.
+ */ export function newRowKey() {
+    return crypto.randomUUID();
+}
+/**
+ * The key of the *n*th row as the record supplied it.
+ *
+ * Deterministic, and that is load-bearing rather than tidy. Seeding is not a
+ * one-time event: `useEntityForm` re-seeds whenever its `entity` changes
+ * identity, and a caller that builds the record inline re-seeds on **every
+ * render**. Minting a fresh random key there produces a draft that differs from
+ * the last one on every pass, so the form engine sees its defaults change
+ * forever and React stops with `Maximum update depth exceeded` — a live hang,
+ * not a test artifact.
+ *
+ * Positional is safe *here* precisely because it describes the record rather
+ * than the live list: re-seeding the same record yields the same keys, and once
+ * the user adds or removes anything the keys already in the draft are carried
+ * through untouched. A row added at runtime takes a {@link newRowKey} instead,
+ * which can never collide with this shape.
+ */ export function seededRowKey(index) {
+    return `row-${index}`;
+}
+/**
+ * Whether a draft value is a usable list of rows.
+ *
+ * A restored draft is `JsonValue`, so a composition member can come back as
+ * anything — a string written by a build before this existed, `null`, or an
+ * array of the wrong shape. Every caller must ask before reading, and the answer
+ * for a value that fails is an empty grid rather than a crash: an unreadable
+ * draft is an unfinished edit, and `restoreEntityDraft` already discards those
+ * per entry rather than losing the whole form.
+ *
+ * A row missing its {@link ROW_KEY} fails, deliberately. Minting one here would
+ * hide the case where a row was written by something that does not know the
+ * contract, and the missing key would then be minted afresh on every render.
+ */ export function isRowDraftArray(value) {
+    return Array.isArray(value) && value.every((row)=>typeof row === 'object' && row !== null && !Array.isArray(row) && typeof row[ROW_KEY] === 'string' && Object.values(row).every((member)=>typeof member === 'string'));
+}
+/** The rows a draft value holds, or an empty list when it holds none usable. */ export function readRowDrafts(value) {
+    return isRowDraftArray(value) ? value : [];
+}
+
+//# sourceMappingURL=EntityRowDraft.js.map

package/dist/types/EntityRowDraft.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityRowDraft.ts"],"sourcesContent":["/**\n * The member a row draft carries its client-side identity in.\n *\n * A `composition`'s rows are editable before the record they belong to has ever\n * been saved, and the child is a **value** — `OrderItem` has no `id`, no domain\n * and no permission namespace\n * ([ADR 0034](../../../../../../docs/adr/0034-composition-metadata.md)). So the\n * only identity a row can have is one the browser mints, and it exists for\n * exactly two jobs: a stable React key, and stable focus across a re-render.\n *\n * `$` is not a legal first character for any member this repo declares, but that\n * is a convention rather than a rule, so `describeChildColumns` **throws** on a\n * child that declares this name instead of trusting it. A silent collision would\n * be a row whose key is overwritten by its own data — it would re-key on every\n * keystroke, lose focus mid-word, and address the wrong row's errors.\n */\nexport const ROW_KEY = '$key';\n\n/**\n * One row of an owned collection, as a form holds it.\n *\n * Members are strings for the reason every draft value is a string — that is\n * what a native input round-trips — and the whole row is JSON, because the\n * workspace autosaves the master's draft through `createJSONStorage`\n * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).\n * The key rides **inside** the row rather than in a parallel array precisely so\n * that it survives that round trip attached to the row it identifies; a parallel\n * structure re-introduces the index identity this exists to avoid.\n *\n * {@link ROW_KEY} never reaches the wire: `reconstructChild` drops it when it\n * rebuilds the child, so the serializer never sees a member the entity does not\n * declare.\n */\nexport type EntityRowDraft = { [member: string]: string };\n\n/**\n * Mints a key for a row the user has just added.\n *\n * `crypto.randomUUID` rather than a counter, because two drafts restored into\n * one session must not collide, and a counter that resets on reload would\n * re-issue keys a persisted draft is still using.\n */\nexport function newRowKey(): string {\n  return crypto.randomUUID();\n}\n\n/**\n * The key of the *n*th row as the record supplied it.\n *\n * Deterministic, and that is load-bearing rather than tidy. Seeding is not a\n * one-time event: `useEntityForm` re-seeds whenever its `entity` changes\n * identity, and a caller that builds the record inline re-seeds on **every\n * render**. Minting a fresh random key there produces a draft that differs from\n * the last one on every pass, so the form engine sees its defaults change\n * forever and React stops with `Maximum update depth exceeded` — a live hang,\n * not a test artifact.\n *\n * Positional is safe *here* precisely because it describes the record rather\n * than the live list: re-seeding the same record yields the same keys, and once\n * the user adds or removes anything the keys already in the draft are carried\n * through untouched. A row added at runtime takes a {@link newRowKey} instead,\n * which can never collide with this shape.\n */\nexport function seededRowKey(index: number): string {\n  return `row-${index}`;\n}\n\n/**\n * Whether a draft value is a usable list of rows.\n *\n * A restored draft is `JsonValue`, so a composition member can come back as\n * anything — a string written by a build before this existed, `null`, or an\n * array of the wrong shape. Every caller must ask before reading, and the answer\n * for a value that fails is an empty grid rather than a crash: an unreadable\n * draft is an unfinished edit, and `restoreEntityDraft` already discards those\n * per entry rather than losing the whole form.\n *\n * A row missing its {@link ROW_KEY} fails, deliberately. Minting one here would\n * hide the case where a row was written by something that does not know the\n * contract, and the missing key would then be minted afresh on every render.\n */\nexport function isRowDraftArray(value: unknown): value is EntityRowDraft[] {\n  return (\n    Array.isArray(value) &&\n    value.every(\n      row =>\n        typeof row === 'object' &&\n        row !== null &&\n        !Array.isArray(row) &&\n        typeof (row as Record<string, unknown>)[ROW_KEY] === 'string' &&\n        Object.values(row as Record<string, unknown>).every(\n          member => typeof member === 'string',\n        ),\n    )\n  );\n}\n\n/** The rows a draft value holds, or an empty list when it holds none usable. */\nexport function readRowDrafts(value: unknown): EntityRowDraft[] {\n  return isRowDraftArray(value) ? value : [];\n}\n"],"names":["ROW_KEY","newRowKey","crypto","randomUUID","seededRowKey","index","isRowDraftArray","value","Array","isArray","every","row","Object","values","member","readRowDrafts"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMA,UAAU,OAAO;AAmB9B;;;;;;CAMC,GACD,OAAO,SAASC;IACd,OAAOC,OAAOC,UAAU;AAC1B;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASC,aAAaC,KAAa;IACxC,OAAO,CAAC,IAAI,EAAEA,OAAO;AACvB;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,gBAAgBC,KAAc;IAC5C,OACEC,MAAMC,OAAO,CAACF,UACdA,MAAMG,KAAK,CACTC,CAAAA,MACE,OAAOA,QAAQ,YACfA,QAAQ,QACR,CAACH,MAAMC,OAAO,CAACE,QACf,OAAO,AAACA,GAA+B,CAACX,QAAQ,KAAK,YACrDY,OAAOC,MAAM,CAACF,KAAgCD,KAAK,CACjDI,CAAAA,SAAU,OAAOA,WAAW;AAItC;AAEA,8EAA8E,GAC9E,OAAO,SAASC,cAAcR,KAAc;IAC1C,OAAOD,gBAAgBC,SAASA,QAAQ,EAAE;AAC5C"}