effect-dynamodb 0.1.0

package/dist/Marshaller.js

@@ -0,0 +1,115 @@
+/**
+ * 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 { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+import { DateTime } from "effect";
+/** Marshall a JS object to a DynamoDB attribute map */
+export const toAttributeMap = (item) => marshall(item, { removeUndefinedValues: true, convertClassInstanceToMap: true });
+/** Unmarshall a DynamoDB attribute map to a JS object */
+export const fromAttributeMap = (item) => unmarshall(item);
+/** Marshall a single value to a DynamoDB attribute value */
+export const toAttributeValue = (value) => marshall({ v: value }).v;
+/** Unmarshall a single DynamoDB attribute value */
+export const fromAttributeValue = (value) => unmarshall({ v: value }).v;
+// ---------------------------------------------------------------------------
+// Date-aware serialization for DynamoEncoding-annotated fields
+// ---------------------------------------------------------------------------
+/**
+ * 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 const serializeDateForDynamo = (value, encoding) => {
+    let epochMs;
+    if (DateTime.isDateTime(value)) {
+        epochMs = DateTime.toEpochMillis(value);
+    }
+    else if (value instanceof Date) {
+        epochMs = value.getTime();
+    }
+    else {
+        throw new Error(`serializeDateForDynamo: unsupported value type: ${typeof value}`);
+    }
+    switch (encoding.storage) {
+        case "string":
+            if (encoding.domain === "DateTime.Zoned" &&
+                DateTime.isDateTime(value) &&
+                DateTime.isZoned(value)) {
+                return DateTime.formatIsoZoned(value);
+            }
+            return new Date(epochMs).toISOString();
+        case "epochMs":
+            return epochMs;
+        case "epochSeconds":
+            return Math.floor(epochMs / 1000);
+    }
+};
+/**
+ * Convert a DynamoDB storage primitive back to the domain value based on DynamoEncoding.
+ */
+export const deserializeDateFromDynamo = (stored, encoding) => {
+    const label = `${encoding.domain}/${encoding.storage}`;
+    switch (encoding.domain) {
+        case "DateTime.Zoned": {
+            if (typeof stored !== "string") {
+                throw new Error(`deserializeDateFromDynamo: expected string for ${label}, got ${typeof stored}`);
+            }
+            try {
+                const match = stored.match(/^(.+)\[(.+)\]$/);
+                if (match) {
+                    const utc = DateTime.makeUnsafe(match[1]);
+                    return DateTime.makeZonedUnsafe(utc, { timeZone: match[2] });
+                }
+                // Offset-only or plain ISO → treat as UTC-zoned
+                const utc = DateTime.makeUnsafe(stored);
+                return DateTime.makeZonedUnsafe(utc, { timeZone: "UTC" });
+            }
+            catch (e) {
+                throw new Error(`deserializeDateFromDynamo: invalid DateTime.Zoned value "${stored}": ${e instanceof Error ? e.message : e}`);
+            }
+        }
+        case "DateTime.Utc": {
+            if (encoding.storage === "string") {
+                if (typeof stored !== "string") {
+                    throw new Error(`deserializeDateFromDynamo: expected string for ${label}, got ${typeof stored}`);
+                }
+                try {
+                    return DateTime.makeUnsafe(stored);
+                }
+                catch (e) {
+                    throw new Error(`deserializeDateFromDynamo: invalid DateTime.Utc value "${stored}": ${e instanceof Error ? e.message : e}`);
+                }
+            }
+            if (typeof stored !== "number" || !Number.isFinite(stored)) {
+                throw new Error(`deserializeDateFromDynamo: expected finite number for ${label}, got ${typeof stored === "number" ? stored : typeof stored}`);
+            }
+            if (encoding.storage === "epochMs")
+                return DateTime.makeUnsafe(stored);
+            return DateTime.makeUnsafe(stored * 1000);
+        }
+        case "Date": {
+            if (encoding.storage === "string") {
+                if (typeof stored !== "string") {
+                    throw new Error(`deserializeDateFromDynamo: expected string for ${label}, got ${typeof stored}`);
+                }
+                const d = new Date(stored);
+                if (Number.isNaN(d.getTime())) {
+                    throw new Error(`deserializeDateFromDynamo: invalid Date value "${stored}"`);
+                }
+                return d;
+            }
+            if (typeof stored !== "number" || !Number.isFinite(stored)) {
+                throw new Error(`deserializeDateFromDynamo: expected finite number for ${label}, got ${typeof stored === "number" ? stored : typeof stored}`);
+            }
+            if (encoding.storage === "epochMs")
+                return new Date(stored);
+            return new Date(stored * 1000);
+        }
+    }
+};
+//# sourceMappingURL=Marshaller.js.map

package/dist/Marshaller.js.map

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

package/dist/Projection.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Projection — Select specific attributes in get/query operations.
+ *
+ * Projections reduce read capacity and network transfer by fetching only
+ * the requested attributes. The result is a partial record (not decoded
+ * through the full entity schema, since projected items may not match).
+ *
+ * Usage:
+ * - projection(["name", "email"]) → { expression, names }
+ * - Pass to get/query operations via ProjectionExpression + ExpressionAttributeNames
+ */
+export interface ProjectionResult {
+    readonly expression: string;
+    readonly names: Record<string, string>;
+}
+/**
+ * Build a ProjectionExpression from a list of attribute names.
+ * Uses ExpressionAttributeNames to safely handle reserved words.
+ *
+ * @example
+ * ```ts
+ * const proj = Projection.projection(["name", "email", "status"])
+ * // proj.expression === "#proj_name, #proj_email, #proj_status"
+ * // proj.names === { "#proj_name": "name", "#proj_email": "email", "#proj_status": "status" }
+ * ```
+ */
+export declare const projection: (attributes: ReadonlyArray<string>) => ProjectionResult;
+//# sourceMappingURL=Projection.d.ts.map

package/dist/Projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Projection.d.ts","sourceRoot":"","sources":["../src/Projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,YAAY,aAAa,CAAC,MAAM,CAAC,KAAG,gBAkB9D,CAAA"}

package/dist/Projection.js

@@ -0,0 +1,39 @@
+/**
+ * Projection — Select specific attributes in get/query operations.
+ *
+ * Projections reduce read capacity and network transfer by fetching only
+ * the requested attributes. The result is a partial record (not decoded
+ * through the full entity schema, since projected items may not match).
+ *
+ * Usage:
+ * - projection(["name", "email"]) → { expression, names }
+ * - Pass to get/query operations via ProjectionExpression + ExpressionAttributeNames
+ */
+/**
+ * Build a ProjectionExpression from a list of attribute names.
+ * Uses ExpressionAttributeNames to safely handle reserved words.
+ *
+ * @example
+ * ```ts
+ * const proj = Projection.projection(["name", "email", "status"])
+ * // proj.expression === "#proj_name, #proj_email, #proj_status"
+ * // proj.names === { "#proj_name": "name", "#proj_email": "email", "#proj_status": "status" }
+ * ```
+ */
+export const projection = (attributes) => {
+    if (attributes.length === 0) {
+        return { expression: "", names: {} };
+    }
+    const names = {};
+    const parts = [];
+    for (const attr of attributes) {
+        const placeholder = `#proj_${attr}`;
+        names[placeholder] = attr;
+        parts.push(placeholder);
+    }
+    return {
+        expression: parts.join(", "),
+        names,
+    };
+};
+//# sourceMappingURL=Projection.js.map

package/dist/Projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Projection.js","sourceRoot":"","sources":["../src/Projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAiC,EAAoB,EAAE;IAChF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;IACtC,CAAC;IAED,MAAM,KAAK,GAA2B,EAAE,CAAA;IACxC,MAAM,KAAK,GAAkB,EAAE,CAAA;IAE/B,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,WAAW,GAAG,SAAS,IAAI,EAAE,CAAA;QACnC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAA;QACzB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IACzB,CAAC;IAED,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5B,KAAK;KACN,CAAA;AACH,CAAC,CAAA"}

package/dist/Query.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Query — Pure description of a DynamoDB query.
+ *
+ * `Query<A>` is a lazy, immutable data type that describes a query. No DynamoDB
+ * calls happen until a terminal (`execute`, `collect`, or `paginate`) is called. All
+ * combinators return a new Query — the original is unchanged.
+ *
+ * Implements Pipeable for ergonomic composition.
+ */
+import type { AttributeValue } from "@aws-sdk/client-dynamodb";
+import { Effect, Pipeable, Stream } from "effect";
+import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
+import type { ValidationError } from "./Errors.js";
+import { type Expr } from "./internal/Expr.js";
+/**
+ * Sort key condition for narrowing query results within a partition.
+ * Exactly one operator should be provided.
+ */
+export type SortKeyCondition = {
+    readonly eq: string;
+} | {
+    readonly lt: string;
+} | {
+    readonly lte: string;
+} | {
+    readonly gt: string;
+} | {
+    readonly gte: string;
+} | {
+    readonly between: readonly [string, string];
+} | {
+    readonly beginsWith: string;
+};
+interface QueryState {
+    readonly tableName: string;
+    readonly indexName: string | undefined;
+    readonly pkField: string;
+    readonly pkValue: string;
+    readonly skField: string | undefined;
+    readonly skConditions: ReadonlyArray<{
+        readonly field: string;
+        readonly condition: SortKeyCondition;
+    }>;
+    readonly exprFilters: ReadonlyArray<Expr>;
+    readonly entityTypes: ReadonlyArray<string>;
+    readonly limitValue: number | undefined;
+    readonly maxPagesValue: number | undefined;
+    readonly scanForward: boolean;
+    readonly consistentRead: boolean;
+    readonly ignoreOwnershipFlag: boolean;
+    readonly exclusiveStartKey: Record<string, AttributeValue> | undefined;
+    readonly isScan: boolean;
+    readonly projection: ReadonlyArray<string> | undefined;
+    readonly projectionPaths: ReadonlyArray<ReadonlyArray<string | number>> | undefined;
+    readonly decoder: (raw: Record<string, unknown>) => Effect.Effect<unknown, ValidationError>;
+    /** Optional effect to resolve table name at execution time (for deferred resolution) */
+    readonly resolveTableName: Effect.Effect<string, never, any> | undefined;
+}
+declare const QueryTypeId: unique symbol;
+export type QueryTypeId = typeof QueryTypeId;
+/**
+ * A lazy, immutable description of a DynamoDB query. No calls happen until
+ * a terminal ({@link execute}, {@link collect}, or {@link paginate}) is invoked.
+ *
+ * All combinators ({@link where}, {@link filter}, {@link limit}, {@link reverse})
+ * return a new Query — the original is unchanged.
+ *
+ * @typeParam A - Decoded item type returned by the query
+ */
+export interface Query<A> extends Pipeable.Pipeable {
+    readonly [QueryTypeId]: QueryTypeId;
+    /** @internal */
+    readonly _state: QueryState;
+    /** @internal */
+    readonly _A: (_: never) => A;
+}
+export declare const make: <A>(config: {
+    readonly tableName: string;
+    readonly indexName: string | undefined;
+    readonly pkField: string;
+    readonly pkValue: string;
+    readonly skField: string | undefined;
+    readonly entityTypes: ReadonlyArray<string>;
+    readonly decoder: (raw: Record<string, unknown>) => Effect.Effect<A, ValidationError>;
+    readonly resolveTableName?: Effect.Effect<string, never, any> | undefined;
+}) => Query<A>;
+/**
+ * Create a scan-mode Query. Shares all combinators and terminals with Query
+ * but uses DynamoDB Scan instead of Query at execution time.
+ * No key condition — only filter expressions and entity type filter.
+ */
+export declare const makeScan: <A>(config: {
+    readonly tableName: string;
+    readonly indexName: string | undefined;
+    readonly entityTypes: ReadonlyArray<string>;
+    readonly decoder: (raw: Record<string, unknown>) => Effect.Effect<A, ValidationError>;
+    readonly resolveTableName?: Effect.Effect<string, never, any> | undefined;
+}) => Query<A>;
+/**
+ * Add a sort key condition to the query.
+ * Only one SK condition is supported (last one wins if multiple are added).
+ */
+export declare const where: {
+    (condition: SortKeyCondition): <A>(self: Query<A>) => Query<A>;
+    <A>(self: Query<A>, condition: SortKeyCondition): Query<A>;
+};
+/**
+ * Set the maximum number of items per DynamoDB page.
+ */
+export declare const limit: {
+    (n: number): <A>(self: Query<A>) => Query<A>;
+    <A>(self: Query<A>, n: number): Query<A>;
+};
+/**
+ * Reverse the sort order (sets ScanIndexForward = false).
+ */
+export declare const reverse: <A>(self: Query<A>) => Query<A>;
+/**
+ * Enable consistent reads for this query (or scan).
+ */
+export declare const consistentRead: {
+    (): <A>(self: Query<A>) => Query<A>;
+    <A>(self: Query<A>): Query<A>;
+};
+/**
+ * Set the maximum number of DynamoDB pages to fetch.
+ * Pagination stops after this many pages even if `LastEvaluatedKey` is present.
+ */
+export declare const maxPages: {
+    (n: number): <A>(self: Query<A>) => Query<A>;
+    <A>(self: Query<A>, n: number): Query<A>;
+};
+/**
+ * Skip the `__edd_e__` entity type filter on this query.
+ * Useful for cross-entity queries or when you know the partition only contains
+ * items of the expected type.
+ */
+export declare const ignoreOwnership: <A>(self: Query<A>) => Query<A>;
+/**
+ * Set the starting cursor for pagination. The cursor is an opaque string
+ * returned by {@link execute} that encodes the DynamoDB `ExclusiveStartKey`.
+ * Pass an empty string to start from the beginning.
+ */
+export declare const startFrom: {
+    (cursor: string): <A>(self: Query<A>) => Query<A>;
+    <A>(self: Query<A>, cursor: string): Query<A>;
+};
+/**
+ * Select specific attributes to return (ProjectionExpression).
+ * Reduces read capacity and network transfer. When projection is active,
+ * items are returned as raw `Record<string, unknown>` instead of decoded
+ * schema instances, since projected items may be partial.
+ */
+export declare const select: {
+    (attributes: ReadonlyArray<string>): <A>(self: Query<A>) => Query<Record<string, unknown>>;
+    <A>(self: Query<A>, attributes: ReadonlyArray<string>): Query<Record<string, unknown>>;
+};
+/**
+ * Add an Expr-based filter expression to the query.
+ * Multiple filterExpr calls are ANDed together.
+ */
+export declare const filterExpr: {
+    (expr: Expr): <A>(self: Query<A>) => Query<A>;
+    <A>(self: Query<A>, expr: Expr): Query<A>;
+};
+/**
+ * Apply path-based projections. Compiles path segments to ProjectionExpression.
+ * When projection is active, items are returned as raw `Record<string, unknown>`.
+ */
+export declare const selectPaths: {
+    (paths: ReadonlyArray<ReadonlyArray<string | number>>): <A>(self: Query<A>) => Query<Record<string, unknown>>;
+    <A>(self: Query<A>, paths: ReadonlyArray<ReadonlyArray<string | number>>): Query<Record<string, unknown>>;
+};
+/**
+ * A single page of query results with an opaque cursor for fetching the next page.
+ */
+export interface Page<A> {
+    readonly items: Array<A>;
+    /** Opaque cursor for the next page, or `null` if there are no more results. */
+    readonly cursor: string | null;
+}
+/**
+ * Execute the query and collect all pages into a single array.
+ */
+export declare const collect: <A>(self: Query<A>) => Effect.Effect<Array<A>, DynamoClientError | ValidationError, DynamoClient>;
+/**
+ * Execute a single DynamoDB page and return a {@link Page} with an opaque cursor.
+ * Combine with {@link startFrom} to iterate through pages:
+ *
+ * ```ts
+ * const first = yield* query.pipe(Query.limit(25), Query.execute)
+ * if (first.cursor) {
+ *   const second = yield* query.pipe(Query.limit(25), Query.startFrom(first.cursor), Query.execute)
+ * }
+ * ```
+ */
+export declare const execute: <A>(self: Query<A>) => Effect.Effect<Page<A>, DynamoClientError | ValidationError, DynamoClient>;
+/**
+ * Execute the query and return a Stream of page arrays.
+ */
+export declare const paginate: <A>(self: Query<A>) => Effect.Effect<Stream.Stream<Array<A>, DynamoClientError | ValidationError>, never, DynamoClient>;
+/**
+ * Execute a count query. Uses `Select: "COUNT"` on DynamoDB — no items are returned.
+ * Returns the total count across all pages (respects maxPages).
+ */
+export declare const count: <A>(self: Query<A>) => Effect.Effect<number, DynamoClientError, DynamoClient>;
+/**
+ * Return the built DynamoDB command input without executing.
+ * Useful for debugging, logging, or passing to DynamoClient directly.
+ */
+export declare const asParams: <A>(self: Query<A>) => Effect.Effect<Record<string, unknown>, never, any>;
+export declare const isQuery: (u: unknown) => u is Query<unknown>;
+export {};
+//# sourceMappingURL=Query.d.ts.map

package/dist/Query.d.ts.map

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