effect-dynamodb 1.8.2 → 1.9.0

package/dist/internal/EntitySchemas.js

@@ -1,794 +0,0 @@
-/**
- * @internal Entity schema building — derived schemas and system field resolution.
- *
- * Extracted from Entity.ts for decomposition. Not part of the public API.
- */
-import { DateTime, Effect, Option, Redacted, Schema, SchemaAST, SchemaGetter, SchemaIssue, } from "effect";
-import { getEncoding, isHidden } from "../DynamoModel.js";
-/**
- * Resolve the effective DynamoEncoding for a model-declared field, applying
- * ConfiguredModel storage overrides on top of schema-level annotations.
- *
- * Precedence: schema annotation (getEncoding) > inferred default (Effect date
- * schemas) > none. ConfiguredModel `storedAs` then overrides storage only,
- * preserving the domain from the schema side when present.
- *
- * Returns `null` if the field is not a date-compatible schema.
- */
-export const resolveFieldEncoding = (fieldSchema, override) => {
-    let encoding = getEncoding(fieldSchema) ?? inferDefaultEncoding(fieldSchema) ?? null;
-    if (override) {
-        encoding = {
-            storage: override.storage,
-            domain: encoding?.domain ?? override.domain,
-        };
-    }
-    return encoding;
-};
-/**
- * Build the field → DynamoEncoding map for a set of model fields, merging
- * ConfiguredModel storage overrides. Used at `Entity.make()` time.
- */
-export const buildFieldEncodings = (modelFields, configuredAttributes) => {
-    const encodings = {};
-    for (const [fieldName, fieldSchema] of Object.entries(modelFields)) {
-        const encoding = resolveFieldEncoding(fieldSchema, configuredAttributes[fieldName]?.encoding);
-        if (encoding)
-            encodings[fieldName] = encoding;
-    }
-    return encodings;
-};
-/** Check if a value is a Schema (has .ast property) vs a plain config object */
-const isSchema = (value) => typeof value === "object" && value !== null && "ast" in value;
-/**
- * Resolve a single TimestampFieldConfig into field name + encoding.
- * Returns [fieldName, encoding | null].
- */
-const resolveTimestampField = (config, defaultName) => {
-    if (config === undefined)
-        return [defaultName, null];
-    if (typeof config === "string")
-        return [config, null];
-    if (isSchema(config)) {
-        const encoding = getEncoding(config);
-        return [defaultName, encoding ?? null];
-    }
-    // Object config: { field?, schema? }
-    const fieldName = config.field ?? defaultName;
-    const encoding = config.schema ? (getEncoding(config.schema) ?? null) : null;
-    return [fieldName, encoding];
-};
-export const resolveSystemFields = (timestamps, versioned, timeSeries, modelFields = {}, configuredAttributes = {}) => {
-    let createdAt = null;
-    let createdAtEncoding = null;
-    let updatedAt = null;
-    let updatedAtEncoding = null;
-    let version = null;
-    if (timestamps === true) {
-        createdAt = "createdAt";
-        updatedAt = "updatedAt";
-    }
-    else if (typeof timestamps === "object" && timestamps !== null) {
-        ;
-        [createdAt, createdAtEncoding] = resolveTimestampField(timestamps.created, "createdAt");
-        [updatedAt, updatedAtEncoding] = resolveTimestampField(timestamps.updated, "updatedAt");
-    }
-    if (versioned === true) {
-        version = "version";
-    }
-    else if (typeof versioned === "object" && versioned !== null) {
-        version = versioned.field ?? "version";
-    }
-    // Time-series entities auto-suppress `updatedAt` — the `orderBy` attribute
-    // serves as the update clock. `createdAt` is preserved.
-    if (timeSeries !== undefined && timeSeries !== null) {
-        if (updatedAt !== null) {
-            if (typeof timestamps === "object" &&
-                timestamps !== null &&
-                timestamps.updated !== undefined) {
-                // eslint-disable-next-line no-console
-                console.warn("[effect-dynamodb] timeSeries entity: `timestamps.updated` is ignored — " +
-                    "the `orderBy` attribute is the event-time clock.");
-            }
-            updatedAt = null;
-            updatedAtEncoding = null;
-        }
-    }
-    // Collision detection: when the model declares a field whose name matches
-    // an active system field, there are two cases:
-    //   (a) Date-compatible schema → library-managed with user override
-    //       support. Encoding reads from the model field (precedence over
-    //       `timestamps` config default).
-    //   (b) Non-date schema → user owns the field entirely. Library skips
-    //       timestamp management for this field (effectively as if the
-    //       corresponding `timestamps.created`/`updated` was never set).
-    //       This preserves existing patterns where users declare `createdAt`
-    //       as a plain string composite.
-    let createdAtCollision = false;
-    if (createdAt && createdAt in modelFields) {
-        const modelEncoding = resolveFieldEncoding(modelFields[createdAt], configuredAttributes[createdAt]?.encoding);
-        if (modelEncoding) {
-            createdAtEncoding = modelEncoding;
-            createdAtCollision = true;
-        }
-        else {
-            // Non-date collision: user owns the field.
-            createdAt = null;
-            createdAtEncoding = null;
-        }
-    }
-    let updatedAtCollision = false;
-    if (updatedAt && updatedAt in modelFields) {
-        const modelEncoding = resolveFieldEncoding(modelFields[updatedAt], configuredAttributes[updatedAt]?.encoding);
-        if (modelEncoding) {
-            updatedAtEncoding = modelEncoding;
-            updatedAtCollision = true;
-        }
-        else {
-            updatedAt = null;
-            updatedAtEncoding = null;
-        }
-    }
-    const versionCollision = !!(version && version in modelFields);
-    return {
-        createdAt,
-        createdAtEncoding,
-        createdAtCollision,
-        updatedAt,
-        updatedAtEncoding,
-        updatedAtCollision,
-        version,
-        versionCollision,
-    };
-};
-// ---------------------------------------------------------------------------
-// Helper: collect primary key composite attribute names
-// ---------------------------------------------------------------------------
-export const primaryKeyComposites = (indexes) => {
-    const primary = indexes.primary;
-    if (!primary)
-        return [];
-    const composites = new Set();
-    for (const attr of primary.pk.composite)
-        composites.add(attr);
-    for (const attr of primary.sk.composite)
-        composites.add(attr);
-    return Array.from(composites);
-};
-// ---------------------------------------------------------------------------
-// Helper: collect all key field names across all indexes
-// ---------------------------------------------------------------------------
-export const allKeyFieldNames = (indexes) => {
-    const fields = new Set();
-    for (const key of Object.keys(indexes)) {
-        const index = indexes[key];
-        if (index) {
-            fields.add(index.pk.field);
-            fields.add(index.sk.field);
-        }
-    }
-    return Array.from(fields);
-};
-// ---------------------------------------------------------------------------
-// Helper: collect all composite attribute names across all indexes
-// ---------------------------------------------------------------------------
-export const allCompositeAttributes = (indexes) => {
-    const attrs = new Set();
-    for (const key of Object.keys(indexes)) {
-        const index = indexes[key];
-        if (index) {
-            for (const attr of index.pk.composite)
-                attrs.add(attr);
-            for (const attr of index.sk.composite)
-                attrs.add(attr);
-        }
-    }
-    return Array.from(attrs);
-};
-const hasFields = (schema) => "fields" in schema && typeof schema.fields === "object";
-export const getFields = (model) => {
-    if (hasFields(model))
-        return model.fields;
-    throw new Error("Entity model must be a Schema.Class or Schema.Struct with .fields");
-};
-/**
- * Infer a default DynamoEncoding for standard Effect date schemas that lack
- * an explicit DynamoEncoding annotation. This enables Pattern B (pure model
- * with Schema.DateTimeUtcFromString etc.) to work without explicit storedAs.
- *
- * Detection uses the typeConstructor annotation from Effect's schema AST.
- */
-export const inferDefaultEncoding = (schema) => {
-    const resolved = SchemaAST.resolve(schema.ast);
-    if (!resolved)
-        return undefined;
-    const tc = resolved.typeConstructor;
-    if (tc?._tag === "effect/DateTime.Utc")
-        return { storage: "string", domain: "DateTime.Utc" };
-    if (tc?._tag === "effect/DateTime.Zoned")
-        return { storage: "string", domain: "DateTime.Zoned" };
-    // Check for native Date via meta annotation
-    const meta = resolved.meta;
-    if (meta?._tag === "isDateValid")
-        return { storage: "string", domain: "Date" };
-    return undefined;
-};
-// ---------------------------------------------------------------------------
-// Self vs. transform schema detection
-// ---------------------------------------------------------------------------
-/**
- * Returns true when the schema is a "self" schema — i.e. it carries no
- * encoding transformation. Self schemas have `ast.encoding === undefined`.
- *
- * - `Schema.DateTimeUtc` — self
- * - `Schema.DateTimeUtcFromString` — transform (encodes to string)
- * - `Schema.RedactedFromValue(...)` — transform
- * - any `.pipe(Schema.decodeTo(...))` chain — transform
- */
-export const isSelfSchema = (schema) => schema.ast.encoding === undefined;
-/**
- * True if the schema is a self DateTime/Date schema that can have its storage
- * configured via a DynamoEncoding annotation. Distinguished from a transform
- * by `ast.encoding === undefined`.
- */
-export const isSelfDateSchema = (schema) => {
-    if (!isSelfSchema(schema))
-        return false;
-    // The self-schema check is necessary but not sufficient — also confirm the
-    // type constructor matches one of the supported date domains.
-    return inferDefaultEncoding(schema) !== undefined;
-};
-/**
- * Returns true when the schema is a transform schema with a date typeConstructor
- * (e.g. `Schema.DateTimeUtcFromString`, `DynamoModel.DateEpochSeconds`).
- * Used to enforce the "transform owns the wire format" policy at Entity.make().
- */
-export const isDateTransform = (schema) => {
-    if (isSelfSchema(schema))
-        return false;
-    return inferDefaultEncoding(schema) !== undefined;
-};
-// ---------------------------------------------------------------------------
-// Self-date schema substitution
-// ---------------------------------------------------------------------------
-/**
- * Convert any input value (string / number / DateTime / Date) to the wire
- * primitive for a given encoding. Used by date substitutes' `encode` path.
- *
- * Wire format precisely matches the legacy `serializeDateForDynamo` output:
- * - `string` storage → ISO 8601 string (UTC for DateTime.Utc / Date; extended
- *   format for DateTime.Zoned)
- * - `epochMs` storage → integer milliseconds since the Unix epoch
- * - `epochSeconds` storage → integer seconds since the Unix epoch (TTL format)
- */
-const toWirePrimitive = (value, encoding) => {
-    let epochMs;
-    let zoned;
-    if (DateTime.isDateTime(value)) {
-        if (DateTime.isZoned(value))
-            zoned = value;
-        epochMs = DateTime.toEpochMillis(value);
-    }
-    else if (value instanceof Date) {
-        epochMs = value.getTime();
-    }
-    else if (typeof value === "string") {
-        epochMs = new Date(value).getTime();
-    }
-    else if (typeof value === "number") {
-        // Numeric inputs are interpreted in the encoding's storage scale already.
-        if (encoding.storage === "epochSeconds")
-            epochMs = value * 1000;
-        else
-            epochMs = value;
-    }
-    else {
-        throw new Error(`[effect-dynamodb] toWirePrimitive: unsupported input ${typeof value} for ${encoding.domain}/${encoding.storage}`);
-    }
-    switch (encoding.storage) {
-        case "string":
-            if (encoding.domain === "DateTime.Zoned" && zoned)
-                return DateTime.formatIsoZoned(zoned);
-            return new Date(epochMs).toISOString();
-        case "epochMs":
-            return epochMs;
-        case "epochSeconds":
-            return Math.floor(epochMs / 1000);
-    }
-};
-/**
- * Build a bidirectional Schema for a given DynamoEncoding.
- *
- * The encoded side is `Schema.Any` so `decode` tolerates either:
- * - the wire primitive (string / number) — the storage-shape input, OR
- * - a domain value (`DateTime.Utc`, `Date`, etc.) — what users typically pass
- *   into `entity.put({...})` and `.set({...})`.
- *
- * The `decode` direction always lifts to the domain type (DateTime.Utc /
- * DateTime.Zoned / Date). The `encode` direction always produces the wire
- * primitive. This makes both `Schema.encode(substituted)` and
- * `Schema.decode(substituted)` work end-to-end regardless of whether the
- * caller passed wire-form or domain-form.
- *
- * @internal
- */
-export const buildDateTransform = (encoding) => {
-    const targetSchema = (() => {
-        switch (encoding.domain) {
-            case "DateTime.Utc":
-                return Schema.DateTimeUtc;
-            case "DateTime.Zoned":
-                return Schema.DateTimeZoned;
-            case "Date":
-                return Schema.DateValid;
-        }
-    })();
-    const liftToDomain = (value) => {
-        if (DateTime.isDateTime(value))
-            return value;
-        if (value instanceof Date) {
-            switch (encoding.domain) {
-                case "DateTime.Utc":
-                    return DateTime.makeUnsafe(value);
-                case "DateTime.Zoned":
-                    return DateTime.makeZonedUnsafe(value, { timeZone: "UTC" });
-                case "Date":
-                    return value;
-            }
-        }
-        if (typeof value === "string") {
-            switch (encoding.domain) {
-                case "DateTime.Utc":
-                    return DateTime.makeUnsafe(value);
-                case "DateTime.Zoned": {
-                    const match = value.match(/^(.+)\[(.+)\]$/);
-                    if (match) {
-                        const utc = DateTime.makeUnsafe(match[1]);
-                        return DateTime.makeZonedUnsafe(utc, { timeZone: match[2] });
-                    }
-                    const utc = DateTime.makeUnsafe(value);
-                    return DateTime.makeZonedUnsafe(utc, { timeZone: "UTC" });
-                }
-                case "Date":
-                    return new Date(value);
-            }
-        }
-        if (typeof value === "number") {
-            const ms = encoding.storage === "epochSeconds" ? value * 1000 : value;
-            switch (encoding.domain) {
-                case "DateTime.Utc":
-                    return DateTime.makeUnsafe(ms);
-                case "DateTime.Zoned":
-                    return DateTime.makeZonedUnsafe(new Date(ms), { timeZone: "UTC" });
-                case "Date":
-                    return new Date(ms);
-            }
-        }
-        return value;
-    };
-    return Schema.Any.pipe(Schema.decodeTo(targetSchema, {
-        decode: SchemaGetter.transformOrFail((value) => {
-            try {
-                return Effect.succeed(liftToDomain(value));
-            }
-            catch {
-                return Effect.fail(new SchemaIssue.InvalidType(Schema.Any.ast, Option.some(value)));
-            }
-        }),
-        encode: SchemaGetter.transformOrFail((value) => {
-            try {
-                return Effect.succeed(toWirePrimitive(value, encoding));
-            }
-            catch {
-                return Effect.fail(new SchemaIssue.InvalidType(Schema.Any.ast, Option.some(value)));
-            }
-        }),
-    }));
-};
-/**
- * Detects `Schema.RedactedFromValue(inner)` fields (and `Schema.Redacted`).
- * The encoded form of these schemas is "Forbidden" by Effect v4 design —
- * encoding bails out to prevent accidental leaks. To make the round-trip work
- * for our use case (write to DynamoDB, read back with Redacted on the domain
- * side), we substitute with a custom transform that explicitly extracts the
- * inner value via `Redacted.value` on encode and rewraps via `Redacted.make`
- * on decode.
- *
- * Returns the inner schema (the wire-format schema) when the field is a
- * Redacted-typed schema, otherwise undefined.
- */
-const tryGetRedactedInner = (schema) => {
-    const resolved = SchemaAST.resolve(schema.ast);
-    if (resolved?.typeConstructor?._tag !== "effect/Redacted")
-        return undefined;
-    // The decoded type is `Redacted<T>` where the inner schema is at
-    // `ast.typeParameters[0]`. Walk the AST and rebuild the Schema via
-    // `Schema.make` so we get a fully-functional Schema (with `.pipe`).
-    const ast = schema.ast;
-    const params = ast.typeParameters;
-    if (!params || params.length === 0)
-        return undefined;
-    const innerAst = params[0];
-    return Schema.make(innerAst);
-};
-/**
- * Build a substitute Schema for a `Schema.RedactedFromValue(inner)` field.
- *
- * The substitute round-trips: produces `Redacted<T>` on the domain side and
- * the inner wire primitive on the encoded side. Both directions tolerate
- * either form on input — a user passing a plain inner value is wrapped via
- * `Redacted.make`; a user passing a `Redacted<T>` instance is unwrapped on
- * encode via `Redacted.value`. This permissive shape lets the put/update
- * paths handle the mixed wire/domain payloads users typically construct
- * (e.g. `.put({ secret: Redacted.make(...) })`).
- *
- * The encoded side is `Schema.Any` so decode tolerates either form; the
- * branch logic in `decode`/`encode` then steers the value to the right
- * representation.
- */
-const buildRedactedSubstitute = (inner) => {
-    return Schema.Any.pipe(Schema.decodeTo(Schema.Redacted(inner), {
-        decode: SchemaGetter.transform((value) => Redacted.isRedacted(value) ? value : Redacted.make(value)),
-        encode: SchemaGetter.transform((r) => Redacted.isRedacted(r) ? Redacted.value(r) : r),
-    }));
-};
-/**
- * Substitute model fields with bidirectional transforms where needed:
- *
- *  - Self date schemas with an effective encoding (annotation or override)
- *    → tolerant date transform that accepts either wire form (string/number)
- *    or domain form (DateTime / Date) on decode, and always produces the
- *    configured wire primitive on encode.
- *  - `Schema.RedactedFromValue(inner)` fields → tolerant Redacted transform
- *    that accepts either form on decode and unwraps to wire primitive on
- *    encode (Effect v4's `RedactedFromValue` forbids encoding by default;
- *    our substitution makes the round-trip work for storage).
- *
- * Existing transform schemas (other than `RedactedFromValue`) are passed
- * through unchanged — the user-declared transform IS the wire format.
- *
- * Schema.Class fields (and Schema.Class fields nested inside Schema.Array,
- * Schema.optional, etc.) are NOT substituted here. Instead, callers run
- * `decode → encode` against the substituted schema: `Schema.decode` is
- * forgiving for Schema.Class (lifts plain objects to instances), and the
- * tolerant date / Redacted substitutes make the decode pass accept both
- * wire and domain values. The subsequent `Schema.encode` produces the
- * canonical wire shape.
- *
- * @internal
- */
-export const substituteSchemas = (modelFields, fieldEncodings) => {
-    const out = {};
-    for (const [name, schema] of Object.entries(modelFields)) {
-        // 1. Self-date substitution. Pattern A: user declared `Schema.DateTimeUtc`
-        //    and chose a wire format via annotation. We substitute with the
-        //    tolerant date transform so the encode pipeline produces the right
-        //    wire primitive.
-        if (isSelfDateSchema(schema)) {
-            const enc = fieldEncodings[name];
-            if (enc) {
-                out[name] = buildDateTransform(enc);
-                continue;
-            }
-        }
-        // 2. RedactedFromValue substitution. Effect v4's `RedactedFromValue`
-        //    forbids encoding by design; substitute with a tolerant Redacted
-        //    transform so the round-trip works for storage.
-        const redactedInner = tryGetRedactedInner(schema);
-        if (redactedInner !== undefined) {
-            out[name] = buildRedactedSubstitute(redactedInner);
-            continue;
-        }
-        // Default: pass through unchanged. Pattern B transforms (DynamoModel.*,
-        // Schema.DateTimeUtcFromString, Schema.NumberFromString, …) own their
-        // wire format directly — `Schema.encode` handles the conversion.
-        out[name] = schema;
-    }
-    return out;
-};
-/**
- * Validate that no model field combines a transform schema with a storage
- * override. The two configuration paths are mutually exclusive: either declare
- * a self schema (`Schema.DateTimeUtc`) and let the annotation drive storage,
- * OR declare a transform and own the wire format yourself — not both.
- *
- * Two override sources are checked:
- *
- *  1. `ConfiguredModel.storedAs` (configured attributes) — surfaces the
- *     override via `configuredAttributes[name].encoding`.
- *
- *  2. `DynamoModel.storedAs(...)` modifier piped onto the field schema —
- *     adds a `DynamoEncoding` annotation directly to the AST. We detect this
- *     by checking whether the field-level annotation disagrees with the
- *     transform's actual wire format (the `inferDefaultEncoding` of the
- *     transform). For an unmodified transform (e.g. `DynamoModel.DateString`
- *     with a matching ISO-string annotation), the two agree and the field is
- *     accepted.
- *
- * Throws at `Entity.make()` time if the conflict is detected.
- *
- * @internal
- */
-export const validateNoTransformOverride = (modelFields, configuredAttributes) => {
-    const conflictMessage = (name) => `[effect-dynamodb] Field "${name}": cannot apply DynamoEncoding storage override to a transform schema. ` +
-        `Either declare a self schema (Schema.DateTimeUtc) and let the annotation drive storage, OR declare a transform and own the wire format — not both.`;
-    for (const [name, schema] of Object.entries(modelFields)) {
-        if (!isDateTransform(schema))
-            continue;
-        // 1. ConfiguredModel.storedAs override?
-        const configOverride = configuredAttributes[name]?.encoding;
-        if (configOverride !== undefined) {
-            throw new Error(conflictMessage(name));
-        }
-        // 2. DynamoModel.storedAs() modifier on the schema itself? The modifier
-        //    applies a `DynamoEncoding` annotation to the AST. Detect a conflict
-        //    by comparing the annotation's storage with the transform's actual
-        //    wire format (read from `ast.encoding[last].to._tag`). Granularity:
-        //    we can distinguish "string" vs "number" wire forms; we cannot
-        //    distinguish epochMs vs epochSeconds at this layer. The string-vs-
-        //    number mismatch covers the most common breaking case.
-        const annotated = getEncoding(schema);
-        if (annotated === undefined)
-            continue;
-        const transformWire = transformWireKind(schema);
-        if (transformWire === undefined)
-            continue;
-        const annotatedKind = annotated.storage === "string" ? "string" : "number";
-        if (transformWire !== annotatedKind) {
-            throw new Error(conflictMessage(name));
-        }
-    }
-};
-/**
- * Read the wire form ("string" or "number") that a transform schema actually
- * encodes to, by walking the encoding chain. Returns undefined when the chain
- * is missing or the leaf isn't a String / Number node.
- */
-const transformWireKind = (schema) => {
-    const enc = schema.ast.encoding;
-    if (!enc || enc.length === 0)
-        return undefined;
-    const leaf = enc[enc.length - 1];
-    if (!leaf)
-        return undefined;
-    const tag = leaf.to._tag;
-    if (tag === "String")
-        return "string";
-    if (tag === "Number")
-        return "number";
-    return undefined;
-};
-export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolvedRefs = [], immutableFields = new Set(), identifierField = undefined, timeSeries = undefined, fieldEncodings = {}) => {
-    // --- Substitute model fields ---
-    // Self date schemas (with effective encoding) are replaced with bidirectional
-    // transforms that produce the configured wire primitive. RedactedFromValue
-    // fields are replaced with a custom bidirectional transform so encoding
-    // round-trips. All other transform schemas are passed through — the user's
-    // transform IS the wire format and we never override it.
-    const fields = substituteSchemas(modelFields, fieldEncodings);
-    // --- Model Schema: pure model fields (for input decode/encode) ---
-    const modelSchema = Schema.Struct(fields);
-    // --- Record Schema: model + system fields ---
-    // System timestamp fields use Schema.DateTimeUtcFromString as the canonical
-    // wire ↔ domain transform when they're library-managed. When the field
-    // collides with a model-declared field, the model's substituted schema is
-    // already in `fields` and we don't add a system-schema entry.
-    const systemSchemaFields = {};
-    if (systemFields.createdAt && !systemFields.createdAtCollision) {
-        systemSchemaFields[systemFields.createdAt] = systemFields.createdAtEncoding
-            ? buildDateTransform(systemFields.createdAtEncoding)
-            : Schema.DateTimeUtcFromString;
-    }
-    if (systemFields.updatedAt && !systemFields.updatedAtCollision) {
-        systemSchemaFields[systemFields.updatedAt] = systemFields.updatedAtEncoding
-            ? buildDateTransform(systemFields.updatedAtEncoding)
-            : Schema.DateTimeUtcFromString;
-    }
-    if (systemFields.version && !systemFields.versionCollision) {
-        systemSchemaFields[systemFields.version] = Schema.Number;
-    }
-    const recordSchema = Schema.Struct({
-        ...fields,
-        ...systemSchemaFields,
-    });
-    // --- System-collision handling for input/update schemas ---
-    // When the model declares a field whose name matches an active system field,
-    // the input shape changes:
-    //   - createdAt / updatedAt → marked optional (user may supply a value or
-    //     leave absent and let the library generate).
-    //   - version → stripped entirely (optimistic locking requires library-
-    //     managed increment; user-supplied values would break the mechanic).
-    // `createdAt` is also treated as immutable in the update schema.
-    const optionalOnCollide = new Set();
-    if (systemFields.createdAtCollision && systemFields.createdAt)
-        optionalOnCollide.add(systemFields.createdAt);
-    if (systemFields.updatedAtCollision && systemFields.updatedAt)
-        optionalOnCollide.add(systemFields.updatedAt);
-    const strippedFromInput = new Set();
-    if (systemFields.versionCollision && systemFields.version)
-        strippedFromInput.add(systemFields.version);
-    const strippedFromUpdate = new Set(strippedFromInput);
-    if (systemFields.createdAtCollision && systemFields.createdAt)
-        strippedFromUpdate.add(systemFields.createdAt);
-    const applySystemCollisionAdjustments = (fieldName, fieldSchema, kind) => {
-        const strippedSet = kind === "update" ? strippedFromUpdate : strippedFromInput;
-        if (strippedSet.has(fieldName))
-            return null;
-        if (optionalOnCollide.has(fieldName))
-            return Schema.optional(fieldSchema);
-        return fieldSchema;
-    };
-    // --- Input Schema: ref-aware (swap ref fields for ID fields when refs present) ---
-    const refFieldSet = new Set(resolvedRefs.map((r) => r.fieldName));
-    const buildInputFieldsAcc = () => {
-        const acc = {};
-        for (const [key, field] of Object.entries(fields)) {
-            if (refFieldSet.has(key))
-                continue;
-            const adjusted = applySystemCollisionAdjustments(key, field, "input");
-            if (adjusted !== null)
-                acc[key] = adjusted;
-        }
-        for (const ref of resolvedRefs) {
-            acc[ref.idFieldName] = ref.identifierSchema;
-        }
-        return acc;
-    };
-    const inputSchema = Schema.Struct(buildInputFieldsAcc());
-    // --- Create Schema: input fields minus identifier (or PK composites as fallback) ---
-    const pkComposites = new Set(primaryKeyComposites(indexes));
-    const createOmitFields = identifierField ? new Set([identifierField]) : pkComposites;
-    const createFieldsAcc = {};
-    for (const [key, field] of Object.entries(fields)) {
-        if (createOmitFields.has(key))
-            continue; // skip identifier/PK composites (auto-generated)
-        if (refFieldSet.has(key))
-            continue; // skip ref fields (replaced by ID fields)
-        const adjusted = applySystemCollisionAdjustments(key, field, "input");
-        if (adjusted !== null)
-            createFieldsAcc[key] = adjusted;
-    }
-    // Add ID fields for each ref (skip if the ref field is an omitted field)
-    for (const ref of resolvedRefs) {
-        if (createOmitFields.has(ref.fieldName))
-            continue;
-        createFieldsAcc[ref.idFieldName] = ref.identifierSchema;
-    }
-    const createSchema = Schema.Struct(createFieldsAcc);
-    // --- Update Schema: optional model fields minus key composites & immutable ---
-    // Each field is wrapped in `Schema.optional` so the key may be omitted
-    // entirely (the structural composer treats absent keys as absent for GSI
-    // composition under v3's two-way classification). The field's value type
-    // matches the model declaration exactly — there is no `null` widening,
-    // because EDD-9025 prevents composites from declaring `null` and the
-    // standard update payload follows the same shape. If the model declares a
-    // non-composite attribute as `Schema.NullOr(X)`, `set({ attr: null })`
-    // still typechecks; the v1.6 `NullishOr` wrap that allowed null on
-    // arbitrary fields (regardless of model declaration) is removed.
-    const buildUpdateFieldsAcc = () => {
-        const acc = {};
-        for (const [key, field] of Object.entries(fields)) {
-            if (pkComposites.has(key))
-                continue;
-            if (immutableFields.has(key))
-                continue;
-            if (refFieldSet.has(key))
-                continue;
-            if (strippedFromUpdate.has(key))
-                continue;
-            acc[key] = Schema.optional(field);
-        }
-        for (const ref of resolvedRefs) {
-            if (pkComposites.has(ref.fieldName))
-                continue;
-            if (immutableFields.has(ref.fieldName))
-                continue;
-            acc[ref.idFieldName] = Schema.optional(ref.identifierSchema);
-        }
-        return acc;
-    };
-    const updateSchema = Schema.Struct(buildUpdateFieldsAcc());
-    // --- Key Schema: primary key composite attributes only ---
-    const keyCompositeNames = primaryKeyComposites(indexes);
-    const keyFields = {};
-    for (const name of keyCompositeNames) {
-        const field = fields[name];
-        if (field)
-            keyFields[name] = field;
-    }
-    const keySchema = Schema.Struct(keyFields);
-    // --- Item Schema: record + key attrs (pk, sk, gsi*) + __edd_e__ ---
-    // Primary pk/sk are guaranteed present on every live item. GSI key fields
-    // are sparse: they're written only when every source composite resolves, and
-    // dropped when any composite is missing or indexPolicy evicts the index.
-    // Stream NewImage / raw query results therefore routinely lack GSI keys —
-    // mark them optional so decodeMarshalledItem decodes sparse items cleanly.
-    const primaryKeyFieldNames = new Set();
-    const primary = indexes.primary;
-    if (primary) {
-        primaryKeyFieldNames.add(primary.pk.field);
-        primaryKeyFieldNames.add(primary.sk.field);
-    }
-    const keyAttrFields = {};
-    for (const fieldName of allKeyFieldNames(indexes)) {
-        keyAttrFields[fieldName] = primaryKeyFieldNames.has(fieldName)
-            ? Schema.String
-            : Schema.optional(Schema.String);
-    }
-    const itemSchema = Schema.Struct({
-        ...fields,
-        ...systemSchemaFields,
-        ...keyAttrFields,
-        __edd_e__: Schema.String,
-    });
-    // --- Deleted Record Schema: record + deletedAt ---
-    const deletedRecordSchema = Schema.Struct({
-        ...fields,
-        ...systemSchemaFields,
-        deletedAt: Schema.String,
-    });
-    // --- Hidden-aware decode schemas: strip DynamoModel.Hidden fields from model/record ---
-    // These are used for "model" and "record" decode modes. Hidden fields are
-    // still present in "item" and "native" modes.
-    const hiddenFieldNames = new Set();
-    for (const [fieldName, fieldSchema] of Object.entries(modelFields)) {
-        if (isHidden(fieldSchema))
-            hiddenFieldNames.add(fieldName);
-    }
-    const hasHiddenFields = hiddenFieldNames.size > 0;
-    const modelVisibleSchema = hasHiddenFields
-        ? Schema.Struct(Object.fromEntries(Object.entries(fields).filter(([k]) => !hiddenFieldNames.has(k))))
-        : modelSchema;
-    const recordVisibleSchema = hasHiddenFields
-        ? Schema.Struct(Object.fromEntries(Object.entries({
-            ...fields,
-            ...systemSchemaFields,
-        }).filter(([k]) => !hiddenFieldNames.has(k))))
-        : recordSchema;
-    // --- Time-series derived schemas ---
-    // `appendInputSchema`: the user-supplied schema, with the same substitution
-    //    rules applied as the model fields (self date schemas → tolerant
-    //    transforms, RedactedFromValue → tolerant Redacted). `Entity.make()`
-    //    enforces that every PK/SK composite + `orderBy` appears in its fields.
-    // `historyRecordSchema`: event-item shape. Substituted model fields + no
-    //    system fields (events are point-in-time facts keyed by `orderBy`).
-    const timeSeriesEnabled = timeSeries !== undefined && timeSeries !== null;
-    const appendInputSchema = timeSeriesEnabled
-        ? (() => {
-            const userSchema = timeSeries.appendInput;
-            const userFields = userSchema.fields;
-            if (!userFields)
-                return userSchema;
-            // Compute encodings for the appendInput fields (annotation +
-            // inferred from typeConstructor for self schemas).
-            const appendEncodings = buildFieldEncodings(userFields, {});
-            const subbedFields = substituteSchemas(userFields, appendEncodings);
-            return Schema.Struct(subbedFields);
-        })()
-        : null;
-    const historyRecordSchema = timeSeriesEnabled
-        ? (() => {
-            const hiddenFilter = (record) => hasHiddenFields
-                ? Object.fromEntries(Object.entries(record).filter(([k]) => !hiddenFieldNames.has(k)))
-                : record;
-            return Schema.Struct(hiddenFilter({ ...fields }));
-        })()
-        : null;
-    return {
-        modelSchema: modelVisibleSchema,
-        recordSchema: recordVisibleSchema,
-        inputSchema: inputSchema,
-        createSchema: createSchema,
-        updateSchema: updateSchema,
-        keySchema: keySchema,
-        itemSchema: itemSchema,
-        deletedRecordSchema: deletedRecordSchema,
-        appendInputSchema: appendInputSchema,
-        historyRecordSchema: historyRecordSchema,
-    };
-};
-// ---------------------------------------------------------------------------
-// Unique constraint field resolver
-// ---------------------------------------------------------------------------
-export const resolveUniqueFields = (def) => Array.isArray(def) ? def : def.fields;
-//# sourceMappingURL=EntitySchemas.js.map