effect-dynamodb 0.1.0

package/dist/Expression.js

@@ -0,0 +1,170 @@
+/**
+ * Expression — Type-safe builders for DynamoDB expressions.
+ *
+ * Produces expression strings with attribute name/value placeholders,
+ * matching the shape used by DynamoDB query/put/update/delete operations.
+ *
+ * Three builder types:
+ * - condition: For conditional puts/deletes (ConditionExpression)
+ * - filter: For query result filtering (FilterExpression)
+ * - update: For update operations (UpdateExpression)
+ */
+import { toAttributeValue } from "./Marshaller.js";
+// Counter for unique placeholder names within a build
+let _counter = 0;
+const nextPlaceholder = () => `v${_counter++}`;
+const resetCounter = () => {
+    _counter = 0;
+};
+const buildComparisonClauses = (op, attrs, names, values) => {
+    const clauses = [];
+    for (const [attr, val] of Object.entries(attrs)) {
+        const nameKey = `#${attr}`;
+        const valKey = `:${nextPlaceholder()}`;
+        names[nameKey] = attr;
+        values[valKey] = toAttributeValue(val);
+        clauses.push(`${nameKey} ${op} ${valKey}`);
+    }
+    return clauses;
+};
+const buildFromInput = (input) => {
+    resetCounter();
+    const names = {};
+    const values = {};
+    const clauses = [];
+    if (input.eq) {
+        clauses.push(...buildComparisonClauses("=", input.eq, names, values));
+    }
+    if (input.ne) {
+        clauses.push(...buildComparisonClauses("<>", input.ne, names, values));
+    }
+    if (input.lt) {
+        clauses.push(...buildComparisonClauses("<", input.lt, names, values));
+    }
+    if (input.le) {
+        clauses.push(...buildComparisonClauses("<=", input.le, names, values));
+    }
+    if (input.gt) {
+        clauses.push(...buildComparisonClauses(">", input.gt, names, values));
+    }
+    if (input.ge) {
+        clauses.push(...buildComparisonClauses(">=", input.ge, names, values));
+    }
+    if (input.between) {
+        for (const [attr, [low, high]] of Object.entries(input.between)) {
+            const nameKey = `#${attr}`;
+            const lowKey = `:${nextPlaceholder()}`;
+            const highKey = `:${nextPlaceholder()}`;
+            names[nameKey] = attr;
+            values[lowKey] = toAttributeValue(low);
+            values[highKey] = toAttributeValue(high);
+            clauses.push(`${nameKey} BETWEEN ${lowKey} AND ${highKey}`);
+        }
+    }
+    if (input.beginsWith) {
+        for (const [attr, prefix] of Object.entries(input.beginsWith)) {
+            const nameKey = `#${attr}`;
+            const valKey = `:${nextPlaceholder()}`;
+            names[nameKey] = attr;
+            values[valKey] = toAttributeValue(prefix);
+            clauses.push(`begins_with(${nameKey}, ${valKey})`);
+        }
+    }
+    if (input.attributeExists) {
+        const attrs = Array.isArray(input.attributeExists)
+            ? input.attributeExists
+            : [input.attributeExists];
+        for (const attr of attrs) {
+            const nameKey = `#${attr}`;
+            names[nameKey] = attr;
+            clauses.push(`attribute_exists(${nameKey})`);
+        }
+    }
+    if (input.attributeNotExists) {
+        const attrs = Array.isArray(input.attributeNotExists)
+            ? input.attributeNotExists
+            : [input.attributeNotExists];
+        for (const attr of attrs) {
+            const nameKey = `#${attr}`;
+            names[nameKey] = attr;
+            clauses.push(`attribute_not_exists(${nameKey})`);
+        }
+    }
+    return {
+        expression: clauses.join(" AND "),
+        names,
+        values,
+    };
+};
+/**
+ * Build a ConditionExpression for conditional puts/deletes.
+ * All clauses are ANDed together.
+ */
+export const condition = (input) => buildFromInput(input);
+/**
+ * Build a FilterExpression for query result filtering.
+ * Same syntax as condition expressions.
+ */
+export const filter = (input) => buildFromInput(input);
+/**
+ * Build an UpdateExpression with SET, REMOVE, ADD, DELETE clauses.
+ */
+export const update = (input) => {
+    resetCounter();
+    const names = {};
+    const values = {};
+    const parts = [];
+    if (input.set) {
+        const setClauses = [];
+        for (const [attr, val] of Object.entries(input.set)) {
+            const nameKey = `#${attr}`;
+            const valKey = `:${nextPlaceholder()}`;
+            names[nameKey] = attr;
+            values[valKey] = toAttributeValue(val);
+            setClauses.push(`${nameKey} = ${valKey}`);
+        }
+        if (setClauses.length > 0) {
+            parts.push(`SET ${setClauses.join(", ")}`);
+        }
+    }
+    if (input.remove && input.remove.length > 0) {
+        const removeClauses = input.remove.map((attr) => {
+            const nameKey = `#${attr}`;
+            names[nameKey] = attr;
+            return nameKey;
+        });
+        parts.push(`REMOVE ${removeClauses.join(", ")}`);
+    }
+    if (input.add) {
+        const addClauses = [];
+        for (const [attr, val] of Object.entries(input.add)) {
+            const nameKey = `#${attr}`;
+            const valKey = `:${nextPlaceholder()}`;
+            names[nameKey] = attr;
+            values[valKey] = toAttributeValue(val);
+            addClauses.push(`${nameKey} ${valKey}`);
+        }
+        if (addClauses.length > 0) {
+            parts.push(`ADD ${addClauses.join(", ")}`);
+        }
+    }
+    if (input.delete) {
+        const deleteClauses = [];
+        for (const [attr, val] of Object.entries(input.delete)) {
+            const nameKey = `#${attr}`;
+            const valKey = `:${nextPlaceholder()}`;
+            names[nameKey] = attr;
+            values[valKey] = toAttributeValue(val);
+            deleteClauses.push(`${nameKey} ${valKey}`);
+        }
+        if (deleteClauses.length > 0) {
+            parts.push(`DELETE ${deleteClauses.join(", ")}`);
+        }
+    }
+    return {
+        expression: parts.join(" "),
+        names,
+        values,
+    };
+};
+//# sourceMappingURL=Expression.js.map

package/dist/Expression.js.map

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

package/dist/KeyComposer.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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";
+/** Index key part definition (pk or sk of an index) */
+export interface KeyPart {
+    readonly field: string;
+    readonly composite: ReadonlyArray<string>;
+}
+/** 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;
+}
+/** 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;
+}
+/** 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>;
+/**
+ * Compose GSI keys for indexes whose composites appear in an update payload.
+ * For each non-primary index, checks if ANY of its composite attributes are in
+ * the update payload. If so, composes the full GSI keys using values merged from
+ * keyRecord (primary key composites) and updatePayload.
+ *
+ * Used by Entity.update to recompose GSI keys when the update touches GSI composites.
+ * Callers should filter out indexes whose composites are targeted by REMOVE operations
+ * before calling — otherwise `extractComposites` will throw on the missing values.
+ */
+export declare const composeGsiKeysForUpdate: (schema: DynamoSchema.DynamoSchema, entityType: string, entityVersion: number, indexes: Record<string, IndexDefinition>, updatePayload: Record<string, unknown>, keyRecord: Record<string, unknown>) => Record<string, string>;
+/**
+ * Thrown when an update provides some but not all composite attributes for a GSI.
+ * Caught by Entity.update and converted to a tagged `ValidationError`.
+ */
+export declare class PartialGsiCompositeError extends Error {
+    readonly indexName: string;
+    readonly provided: ReadonlyArray<string>;
+    readonly missing: ReadonlyArray<string>;
+    readonly required: ReadonlyArray<string>;
+    constructor(indexName: string, provided: ReadonlyArray<string>, missing: ReadonlyArray<string>, required: ReadonlyArray<string>);
+}
+/**
+ * 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;
+//# 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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"}

package/dist/KeyComposer.js

@@ -0,0 +1,257 @@
+/**
+ * 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 { DateTime } from "effect";
+import { composeClusteredSortKey, composeCollectionKey, composeIsolatedSortKey, composeKey, } from "./DynamoSchema.js";
+/** Normalize a GsiConfig (entity input) to an IndexDefinition (internal format). */
+export const normalizeGsiConfig = (config) => {
+    // Detect old format and give helpful migration error
+    if ("index" in config && typeof config.index === "object") {
+        throw new Error(`[EDD-9003] GsiConfig uses old format with "index" property. ` +
+            `Migrate to: { name: "gsi1", pk: { field: "gsi1pk", composite: [...] }, sk: { field: "gsi1sk", composite: [...] } }`);
+    }
+    if (!config.name || !config.pk || !config.sk) {
+        throw new Error(`[EDD-9003] Invalid GsiConfig: requires name, pk: { field, composite }, sk: { field, composite }`);
+    }
+    return {
+        index: config.name,
+        collection: config.collection,
+        type: config.type ?? "isolated",
+        pk: { field: config.pk.field, composite: [...config.pk.composite] },
+        sk: { field: config.sk.field, composite: [...config.sk.composite] },
+    };
+};
+/**
+ * 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 const extractComposites = (composite, record) => composite.map((attr) => {
+    const value = record[attr];
+    if (value === undefined || value === null) {
+        throw new Error(`Missing composite attribute "${attr}" in record`);
+    }
+    return serializeValue(value);
+});
+/**
+ * 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 const tryExtractComposites = (composite, record) => {
+    const values = [];
+    for (const attr of composite) {
+        const value = record[attr];
+        if (value === undefined || value === null)
+            return undefined;
+        values.push(serializeValue(value));
+    }
+    return values;
+};
+/**
+ * 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 const serializeValue = (value) => {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value).padStart(16, "0");
+    if (typeof value === "bigint")
+        return String(value).padStart(38, "0");
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    // DateTime types → ISO string (Zoned normalized to UTC for sort order)
+    if (typeof value === "object" && value !== null && DateTime.isDateTime(value)) {
+        return DateTime.formatIso(value);
+    }
+    // Native Date
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+};
+/**
+ * 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 const composePk = (schema, entityType, index, record) => {
+    const composites = extractComposites(index.pk.composite, record);
+    const names = [...index.pk.composite];
+    const collection = index.collection;
+    if (collection !== undefined) {
+        // Collection index — PK uses collection name
+        const collectionName = Array.isArray(collection) ? collection[0] : collection;
+        return composeCollectionKey(schema, collectionName, composites, { casing: index.casing, names });
+    }
+    // Regular entity index — PK uses entity type
+    return composeKey(schema, entityType, composites, { casing: index.casing, names });
+};
+/**
+ * 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 const composeSk = (schema, entityType, entityVersion, index, record) => {
+    const composites = extractComposites(index.sk.composite, record);
+    const names = [...index.sk.composite];
+    const collection = index.collection;
+    const collectionType = index.type ?? "isolated";
+    if (collection !== undefined) {
+        if (collectionType === "clustered") {
+            // For sub-collections (collection: ["parent", "child"]) the FULL hierarchy
+            // is written into the SK so a begins_with query at any level matches.
+            return composeClusteredSortKey(schema, collection, entityType, entityVersion, composites, {
+                casing: index.casing,
+                names,
+            });
+        }
+        // Isolated
+        return composeIsolatedSortKey(schema, entityType, entityVersion, composites, {
+            casing: index.casing,
+            names,
+        });
+    }
+    // Non-collection — simple entity key
+    return composeKey(schema, entityType, composites, { casing: index.casing, names });
+};
+/**
+ * Compose all key attributes for a single index.
+ * Returns a record mapping field names to composed key values.
+ */
+export const composeIndexKeys = (schema, entityType, entityVersion, index, record) => ({
+    [index.pk.field]: composePk(schema, entityType, index, record),
+    [index.sk.field]: composeSk(schema, entityType, entityVersion, index, record),
+});
+/**
+ * Non-throwing variant of composeIndexKeys. Returns undefined if any composite
+ * attribute is missing. Used for sparse GSI support.
+ */
+export const tryComposeIndexKeys = (schema, entityType, entityVersion, index, record) => {
+    if (tryExtractComposites(index.pk.composite, record) === undefined)
+        return undefined;
+    if (tryExtractComposites(index.sk.composite, record) === undefined)
+        return undefined;
+    return composeIndexKeys(schema, entityType, entityVersion, index, record);
+};
+/**
+ * Compose keys for all indexes of an entity.
+ * Returns a flat record of all key field -> value mappings.
+ */
+export const composeAllKeys = (schema, entityType, entityVersion, indexes, record) => {
+    const result = {};
+    for (const [indexName, index] of Object.entries(indexes)) {
+        if (indexName === "primary") {
+            // Primary index always required — throws on missing composites
+            Object.assign(result, composeIndexKeys(schema, entityType, entityVersion, index, record));
+        }
+        else {
+            // GSI — sparse-aware: skip if any composite is missing
+            const keys = tryComposeIndexKeys(schema, entityType, entityVersion, index, record);
+            if (keys !== undefined)
+                Object.assign(result, keys);
+        }
+    }
+    return result;
+};
+/**
+ * Compose GSI keys for indexes whose composites appear in an update payload.
+ * For each non-primary index, checks if ANY of its composite attributes are in
+ * the update payload. If so, composes the full GSI keys using values merged from
+ * keyRecord (primary key composites) and updatePayload.
+ *
+ * Used by Entity.update to recompose GSI keys when the update touches GSI composites.
+ * Callers should filter out indexes whose composites are targeted by REMOVE operations
+ * before calling — otherwise `extractComposites` will throw on the missing values.
+ */
+export const composeGsiKeysForUpdate = (schema, entityType, entityVersion, indexes, updatePayload, keyRecord) => {
+    const result = {};
+    for (const [indexName, index] of Object.entries(indexes)) {
+        if (indexName === "primary")
+            continue;
+        const allComposites = [...index.pk.composite, ...index.sk.composite];
+        const touchedComposites = allComposites.filter((attr) => attr in updatePayload);
+        if (touchedComposites.length > 0) {
+            const merged = { ...keyRecord, ...updatePayload };
+            const missingComposites = allComposites.filter((attr) => merged[attr] === undefined || merged[attr] === null);
+            if (missingComposites.length > 0) {
+                throw new PartialGsiCompositeError(indexName, touchedComposites, missingComposites, allComposites);
+            }
+            Object.assign(result, composeIndexKeys(schema, entityType, entityVersion, index, merged));
+        }
+    }
+    return result;
+};
+/**
+ * Thrown when an update provides some but not all composite attributes for a GSI.
+ * Caught by Entity.update and converted to a tagged `ValidationError`.
+ */
+export class PartialGsiCompositeError extends Error {
+    indexName;
+    provided;
+    missing;
+    required;
+    constructor(indexName, provided, missing, required) {
+        super(`Partial GSI composite update on index "${indexName}": ` +
+            `provided [${provided.join(", ")}] but missing [${missing.join(", ")}]. ` +
+            `When updating any composite for a GSI, all composites must be provided: [${required.join(", ")}]`);
+        this.name = "PartialGsiCompositeError";
+        this.indexName = indexName;
+        this.provided = provided;
+        this.missing = missing;
+        this.required = required;
+    }
+}
+/**
+ * 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 const composeSortKeyPrefix = (schema, entityType, entityVersion, index, record) => {
+    // Collect available composites and their names (stop at first missing)
+    const available = [];
+    const names = [];
+    for (const attr of index.sk.composite) {
+        const value = record[attr];
+        if (value === undefined || value === null)
+            break;
+        available.push(serializeValue(value));
+        names.push(attr);
+    }
+    const collection = index.collection;
+    const collectionType = index.type ?? "isolated";
+    if (collection !== undefined) {
+        if (collectionType === "clustered") {
+            // For sub-collections, pass the full hierarchy so the SK prefix matches
+            // the same hierarchy written by composeSk during put.
+            return composeClusteredSortKey(schema, collection, entityType, entityVersion, available, {
+                casing: index.casing,
+                names,
+            });
+        }
+        return composeIsolatedSortKey(schema, entityType, entityVersion, available, {
+            casing: index.casing,
+            names,
+        });
+    }
+    return composeKey(schema, entityType, available, { casing: index.casing, names });
+};
+//# sourceMappingURL=KeyComposer.js.map

package/dist/KeyComposer.js.map

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

package/dist/Marshaller.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Marshaller — Thin wrapper around @aws-sdk/util-dynamodb for converting
+ * between JS objects and DynamoDB attribute maps, plus date-aware serialization
+ * for DynamoEncoding-annotated fields.
+ */
+import type { AttributeValue } from "@aws-sdk/client-dynamodb";
+import { DateTime } from "effect";
+import type { DynamoEncoding } from "./DynamoModel.js";
+/** Marshall a JS object to a DynamoDB attribute map */
+export declare const toAttributeMap: (item: Record<string, unknown>) => Record<string, AttributeValue>;
+/** Unmarshall a DynamoDB attribute map to a JS object */
+export declare const fromAttributeMap: (item: Record<string, AttributeValue>) => Record<string, unknown>;
+/** Marshall a single value to a DynamoDB attribute value */
+export declare const toAttributeValue: (value: unknown) => AttributeValue;
+/** Unmarshall a single DynamoDB attribute value */
+export declare const fromAttributeValue: (value: AttributeValue) => unknown;
+/**
+ * Convert a domain date value to the storage primitive based on DynamoEncoding.
+ *
+ * Domain types supported:
+ * - `DateTime.Utc` → ISO string, epoch ms, or epoch seconds
+ * - `DateTime.Zoned` → extended ISO string (only "string" storage)
+ * - `Date` → ISO string, epoch ms, or epoch seconds
+ */
+export declare const serializeDateForDynamo: (value: unknown, encoding: DynamoEncoding) => string | number;
+/**
+ * Convert a DynamoDB storage primitive back to the domain value based on DynamoEncoding.
+ */
+export declare const deserializeDateFromDynamo: (stored: unknown, encoding: DynamoEncoding) => DateTime.Utc | DateTime.Zoned | Date;
+//# sourceMappingURL=Marshaller.d.ts.map

package/dist/Marshaller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Marshaller.d.ts","sourceRoot":"","sources":["../src/Marshaller.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,uDAAuD;AACvD,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CACV,CAAA;AAElF,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAC5E,CAAA;AAElB,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,cAA2C,CAAA;AAE7F,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,GAAI,OAAO,cAAc,KAAG,OAAqC,CAAA;AAMhG;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,OAAO,EACd,UAAU,cAAc,KACvB,MAAM,GAAG,MAyBX,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,OAAO,EACf,UAAU,cAAc,KACvB,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,KAAK,GAAG,IAsElC,CAAA"}