@effect-dynamodb/schema 1.9.0

package/dist/KeyComposer.d.ts

@@ -0,0 +1,264 @@
+/**
+ * KeyComposer — Composite key composition for DynamoDB keys.
+ *
+ * v2 uses attribute-list composition (composite: ["userId"]) instead of
+ * template strings ("USER#${userId}"). The DynamoSchema module handles
+ * the key format; KeyComposer extracts attribute values and delegates.
+ */
+import type * as DynamoSchema from "./DynamoSchema.js";
+import type { CompositeKeyHoleError } from "./Errors.js";
+/** Index key part definition (pk or sk of an index) */
+export interface KeyPart {
+    readonly field: string;
+    readonly composite: ReadonlyArray<string>;
+}
+/**
+ * Per-half policy value controlling how `Entity.update` and time-series
+ * `.append` handle a GSI half the writer touches but can't compose.
+ *
+ * Per-half evaluation gate (v1.7.1): a half is *touched* iff at least one of
+ * its composite names appears in the update payload (regardless of value,
+ * including `undefined`) OR appears in `Entity.remove([...])`. Untouched
+ * halves are skipped entirely — no SET, no REMOVE, no policy fires.
+ *
+ * For *touched* halves the policy decides the outcome when the structural
+ * rule can't compose (empty leading prefix OR hole pattern):
+ * - `"sparse"` — REMOVE this half's key attribute (the half drops out of the
+ *   GSI). The other half follows its own per-half outcome independently —
+ *   there is no GSI-wide cascade. The DDB projection rule means an item with
+ *   only one key attribute is invisible in the GSI; the surviving half's
+ *   value is preserved for rejoin without other writers re-firing.
+ * - `"preserve"` — noop (leave the stored key for this half untouched). The
+ *   stored value may go stale until either (a) the next write that touches
+ *   this half supplies enough composites to recompose, or (b) a composite of
+ *   this half is named in `Entity.remove([...])` — the cascade override
+ *   then REMOVEs this half's key.
+ *
+ * Halves not declared in `indexPolicy` default to `"preserve"`. See
+ * `DESIGN.md §7 Policy-Aware GSI Composition` for the full decision rules
+ * (per-half evaluation gate, per-half outcome, cascade override, decision
+ * table).
+ */
+export type IndexPolicyKey = "sparse" | "preserve";
+/**
+ * Per-half index policy declaration. Both halves default to `"preserve"`
+ * when omitted (or when `indexPolicy` is omitted entirely from the GSI
+ * config).
+ *
+ * The standard composition path has only payload-level information (no
+ * read-before-write), so per-attribute policy callbacks were removed in
+ * v3 — within a single half, per-attribute mixing has no coherent semantic
+ * because a half is a single concatenated string.
+ */
+export interface IndexPolicy {
+    readonly pk?: IndexPolicyKey | undefined;
+    readonly sk?: IndexPolicyKey | undefined;
+}
+/** Index definition for primary or secondary index (internal format) */
+export interface IndexDefinition {
+    readonly index?: string | undefined;
+    readonly collection?: string | ReadonlyArray<string> | undefined;
+    readonly type?: "isolated" | "clustered" | undefined;
+    readonly pk: KeyPart;
+    readonly sk: KeyPart;
+    readonly casing?: DynamoSchema.Casing | undefined;
+    /**
+     * Optional per-half policy for `Entity.update` and `.append`. Not consulted
+     * on `put()` — put always omits a GSI's keys when any of its composites is
+     * missing.
+     */
+    readonly indexPolicy?: IndexPolicy | undefined;
+}
+/** GSI definition as specified on Entity.make() indexes config.
+ * Mirrors the primaryKey structure with an added `name` for the physical GSI. */
+export interface GsiConfig {
+    /** Physical GSI name (e.g., `"gsi1"`). */
+    readonly name: string;
+    /** Optional collection name. String for single, array for sub-collections. */
+    readonly collection?: string | ReadonlyArray<string> | undefined;
+    /** SK ordering mode. `"isolated"` (default) puts entity type before composites; `"clustered"` puts entity type after composites (required for sub-collections). */
+    readonly type?: "isolated" | "clustered" | undefined;
+    /** Partition key: physical field name + composite attributes. */
+    readonly pk: KeyPart;
+    /** Sort key: physical field name + composite attributes. */
+    readonly sk: KeyPart;
+    /**
+     * Per-half sparse/preserve policy. Applied by `Entity.update` and
+     * time-series `.append`. Defaults to `"preserve"` on each half. Not
+     * applied on `put()`. See `DESIGN.md §7 Policy-Aware GSI Composition`.
+     */
+    readonly indexPolicy?: IndexPolicy | undefined;
+}
+/** Normalize a GsiConfig (entity input) to an IndexDefinition (internal format). */
+export declare const normalizeGsiConfig: (config: GsiConfig) => IndexDefinition;
+/**
+ * Extract composite attribute values from an entity record.
+ *
+ * Given composite: ["tenantId", "email"] and record: { tenantId: "t-1", email: "a@b.com" }
+ * Returns: ["t-1", "a@b.com"]
+ */
+export declare const extractComposites: (composite: ReadonlyArray<string>, record: Record<string, unknown>) => ReadonlyArray<string>;
+/**
+ * Non-throwing variant of extractComposites. Returns undefined when any
+ * composite attribute is missing or null. Used for sparse GSI support —
+ * if a GSI's composites aren't all present, the index is simply skipped.
+ */
+export declare const tryExtractComposites: (composite: ReadonlyArray<string>, record: Record<string, unknown>) => ReadonlyArray<string> | undefined;
+/**
+ * Serialize a value for use in a composite key.
+ *
+ * Numeric values are zero-padded for correct lexicographic sort order:
+ * - number → 16-digit zero-padded string (covers Number.MAX_SAFE_INTEGER)
+ * - bigint → 38-digit zero-padded string (covers DynamoDB's max precision)
+ *
+ * DateTime values are formatted as ISO strings for correct sort order:
+ * - DateTime.Zoned → ISO string with offset (preserves timezone info)
+ * - DateTime.Utc → ISO string
+ * - Date → ISO string
+ */
+export declare const serializeValue: (value: unknown) => string;
+/**
+ * Compose a partition key for an entity index.
+ *
+ * For non-collection indexes: `$schema#v<version>#entityType#attr1#attr2`
+ * For collection indexes: `$schema#v<version>#collectionName#attr1#attr2`
+ */
+export declare const composePk: (schema: DynamoSchema.DynamoSchema, entityType: string, index: IndexDefinition, record: Record<string, unknown>) => string;
+/**
+ * Compose a sort key for an entity index.
+ *
+ * For isolated indexes: `$schema#v<version>#entityType_version#attr1#attr2`
+ * For clustered indexes: `$schema#v<version>#collectionName#entityType_version#attr1#attr2`
+ * For non-collection indexes: `$schema#v<version>#entityType#attr1#attr2`
+ */
+export declare const composeSk: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, index: IndexDefinition, record: Record<string, unknown>) => string;
+/**
+ * Compose all key attributes for a single index.
+ * Returns a record mapping field names to composed key values.
+ */
+export declare const composeIndexKeys: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, index: IndexDefinition, record: Record<string, unknown>) => Record<string, string>;
+/**
+ * Non-throwing variant of composeIndexKeys. Returns undefined if any composite
+ * attribute is missing. Used for sparse GSI support.
+ */
+export declare const tryComposeIndexKeys: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, index: IndexDefinition, record: Record<string, unknown>) => Record<string, string> | undefined;
+/**
+ * Compose keys for all indexes of an entity.
+ * Returns a flat record of all key field -> value mappings.
+ */
+export declare const composeAllKeys: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, indexes: Record<string, IndexDefinition>, record: Record<string, unknown>) => Record<string, string>;
+/**
+ * Result of policy-aware GSI update composition.
+ *
+ * - `sets`: map of GSI key field name → composed value (emit as SET clauses).
+ * - `removes`: list of GSI key field names to REMOVE (item drops out of GSI).
+ *
+ * `sets` and `removes` are mutually exclusive — a single field never appears
+ * in both for the same update.
+ */
+export interface GsiUpdateResult {
+    readonly sets: Record<string, string>;
+    readonly removes: ReadonlyArray<string>;
+}
+/**
+ * Compose a sort key from the leading prefix `[sk_0, ..., sk_(stopBefore-1)]`
+ * of an index's SK composites. Used by v3's structural composition rule when a
+ * trailing SK composite is absent and the half's `indexPolicy.sk` is
+ * `"preserve"` (or absent — defaults to preserve), or when a hole pattern is
+ * encountered under `"sparse"`.
+ *
+ * `stopBefore === 0` produces the bare entity/collection prefix with no
+ * composite values (the item still belongs to the GSI but at the broadest
+ * scope — `begins_with(sk, "<prefix>")` matches it).
+ *
+ * See `DESIGN.md §7 Policy-Aware GSI Composition`.
+ */
+export declare const composeSkPrefixUpTo: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, index: IndexDefinition, record: Record<string, unknown>, stopBefore: number) => string;
+/**
+ * Policy-aware GSI key composition for `Entity.update` and time-series
+ * `.append` — v1.7.1 per-half structural composition with per-half evaluation
+ * gate and per-half cascade.
+ *
+ * **Per-half evaluation gate (reframed in v1.7.3 as a skip-predicate).** Each
+ * half (PK and SK) is independently asked one question: *can this half be
+ * safely skipped?* The gate exists for exactly one reason — multi-writer
+ * protection: prevent writer A from clobbering keys for halves it doesn't
+ * own when writer B does own them. The skip-predicate states that purpose
+ * directly: skip iff multi-writer protection actually applies (the half has
+ * composites, no composite was explicitly removed, and every composite is
+ * absent from BOTH `updatePayload` AND `keyRecord` — so this writer is
+ * genuinely not claiming ownership of this half on this call). If the half
+ * cannot be safely skipped, it is evaluated by the structural rule.
+ *
+ * Pre-v1.7.3 the predicate was inverted ("list cases for which to evaluate"
+ * as a chain of `||` clauses) and had to enumerate every shape: payload
+ * membership (v1.7.0), `removedSet` membership (v1.7.1), `keyRecord`
+ * membership (v1.7.2). Each missed shape required another tactical patch:
+ * v1.7.1 missed the multi-writer leak (#41), v1.7.2 missed the
+ * PK-composites-only case (#43), v1.7.2 then missed the empty-composite-half
+ * case (#46) because every `.some(...)` clause trivially returned `false`
+ * for an empty composite array. The skip-predicate closes the entire class
+ * of degenerate-case bugs structurally.
+ *
+ * **Two-way payload classification.**
+ * - **present** (`attr: <value>` in payload, or inherited from `keyRecord`)
+ *   — value is used in composition.
+ * - **absent** (key omitted, or `attr: null`, or `attr: undefined`) — the
+ *   structural rule treats all three identically.
+ *
+ * **Per-half outcome (v1.7.1 unified rule).** For each touched half:
+ * 1. Run the structural rule (longest leading prefix of present values in
+ *    the merged record).
+ * 2. If the prefix is non-empty AND there's no hole → SET (full or truncated).
+ * 3. Otherwise (empty leading prefix OR hole pattern):
+ *    - `'sparse'` → REMOVE this half's key.
+ *    - `'preserve'` AND any composite of this half is in `removedSet` →
+ *      REMOVE (cascade override under preserve).
+ *    - `'preserve'` AND no composite in `removedSet` → noop (stored key
+ *      retained, may be stale until next write touches the half).
+ *
+ * **Per-half roll-up (v1.7.1).** Each half's outcome applies to its own key
+ * attribute only. PK dropping doesn't drop SK; SK dropping doesn't drop PK.
+ * The item may be invisible in the GSI during a single-half-dropped period
+ * (DDB projection rule needs both keys for query visibility), but the
+ * surviving half's value persists for rejoin without other writers re-firing.
+ * The v1.7.0 GSI-wide cascade is gone.
+ *
+ * **`Entity.remove([attr])` cascade (v1.7.1: per-half).** Composites in
+ * `removedSet` contribute to the merged record as "absent" (same as
+ * undefined-in-payload) AND make their containing half "touched" for the
+ * evaluation gate AND trigger the cascade override under preserve. The
+ * cascade no longer drops both halves of every GSI containing the cleared
+ * attribute — only the half(s) whose composite list contains it.
+ *
+ * See `DESIGN.md §7 Policy-Aware GSI Composition` for the full decision
+ * table and worked multi-writer examples.
+ */
+export declare const composeGsiKeysForUpdatePolicyAware: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, indexes: Record<string, IndexDefinition>, updatePayload: Record<string, unknown>, keyRecord: Record<string, unknown>, options?: {
+    readonly removedSet?: ReadonlySet<string> | undefined;
+}) => GsiUpdateResult;
+/** @internal — re-export for documentation cross-reference. */
+export type { CompositeKeyHoleError };
+/**
+ * Compose a partial sort key prefix for query operations.
+ * Used when not all SK composite attributes are provided.
+ *
+ * For example, if SK composite is ["department", "hireDate"] and only "department"
+ * is provided, this generates a begins_with prefix.
+ */
+export declare const composeSortKeyPrefix: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, index: IndexDefinition, record: Record<string, unknown>) => string;
+/**
+ * Compose an event-item sort key by decorating the current-item SK.
+ *
+ * Given `currentSk = "$app#v1#telemetry_1"` and `orderByValue = 42`, returns
+ * `"$app#v1#telemetry_1#e#0000000000000042"` (with default lowercase casing).
+ */
+export declare const composeEventSk: (currentSk: string, orderByValue: unknown, casing?: DynamoSchema.Casing) => string;
+/**
+ * Compose the prefix used to scope `.history()` queries to event items only.
+ *
+ * Given `currentSk = "$app#v1#telemetry_1"`, returns
+ * `"$app#v1#telemetry_1#e#"`.
+ */
+export declare const composeEventSkPrefix: (currentSk: string, casing?: DynamoSchema.Casing) => string;
+//# sourceMappingURL=KeyComposer.d.ts.map

package/dist/KeyComposer.d.ts.map

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