effect-dynamodb 0.1.0

package/dist/Collection.js

@@ -0,0 +1,195 @@
+/**
+ * Collection — Multi-entity queries across a shared table/index.
+ *
+ * A Collection groups entities that share a common index. Querying a Collection
+ * returns items of all member entity types, each decoded through its own schema.
+ * Entity selectors narrow a collection query to a single entity type.
+ *
+ * Collections are built from Entity index definitions that share a `collection` name.
+ */
+import { Effect } from "effect";
+import * as DynamoSchema from "./DynamoSchema.js";
+import { ValidationError } from "./Errors.js";
+import * as KeyComposer from "./KeyComposer.js";
+import * as Query from "./Query.js";
+// ---------------------------------------------------------------------------
+// Collection.make()
+// ---------------------------------------------------------------------------
+/**
+ * Create a Collection from a set of entities that share an index with a common collection name.
+ *
+ * @param name - The collection name (must match a `collection` property in an entity's index definition)
+ * @param entities - Map of entity names to Entity instances
+ * @returns A Collection with a `.query()` method and per-entity selector methods
+ */
+export const make = (name, entities) => {
+    // Discover the shared index — find the first entity's index that has this collection name
+    const entityEntries = Object.entries(entities);
+    if (entityEntries.length === 0) {
+        throw new Error(`Collection "${name}" requires at least one entity`);
+    }
+    // Find the shared index definition across entities
+    let sharedIndexName;
+    let sharedPkField;
+    let sharedSkField;
+    let sharedDynamoIndexName;
+    let sharedSchema;
+    let collectionType = "isolated";
+    for (const [, entity] of entityEntries) {
+        for (const [indexName, indexDef] of Object.entries(entity.indexes)) {
+            if (indexName === "primary")
+                continue;
+            const coll = indexDef.collection;
+            if (coll === name || (Array.isArray(coll) && coll.includes(name))) {
+                sharedIndexName = indexName;
+                sharedPkField = indexDef.pk.field;
+                sharedSkField = indexDef.sk.field;
+                sharedDynamoIndexName = indexDef.index;
+                sharedSchema = entity._schema;
+                collectionType = indexDef.type ?? "isolated";
+                break;
+            }
+        }
+        if (sharedIndexName)
+            break;
+    }
+    if (!sharedIndexName || !sharedPkField || !sharedSchema) {
+        throw new Error(`No entity in collection "${name}" has an index with collection: "${name}"`);
+    }
+    // Compute the SK prefix for clustered collections.
+    // For sub-collections (collection: ["parent", "child"]), the prefix includes
+    // the hierarchy from the root up to and including this collection name.
+    let collectionSkPrefix;
+    if (collectionType === "clustered" && sharedSkField) {
+        // Find the collection hierarchy from the first entity's index definition
+        const firstIndex = entityEntries[0][1].indexes[sharedIndexName];
+        const coll = firstIndex.collection;
+        const casing = firstIndex.casing ?? sharedSchema.casing;
+        if (Array.isArray(coll)) {
+            // Sub-collection: include hierarchy up to and including the target name
+            const idx = coll.indexOf(name);
+            const hierarchy = coll.slice(0, idx + 1);
+            const pre = DynamoSchema.prefix(sharedSchema);
+            const casedNames = hierarchy.map((n) => DynamoSchema.applyCasing(n, casing));
+            collectionSkPrefix = `${pre}#${casedNames.join("#")}`;
+        }
+        else {
+            // Simple collection: just the collection name
+            collectionSkPrefix = DynamoSchema.composeCollectionKey(sharedSchema, name, [], {
+                casing,
+            });
+        }
+    }
+    // Build entity type discriminator lookup
+    const entityByType = new Map();
+    const entityTypes = [];
+    for (const [key, entity] of entityEntries) {
+        entityByType.set(entity.entityType, { key, entity });
+        entityTypes.push(entity.entityType);
+    }
+    // Collection decoder: decode and group items by entity type
+    const collectionDecoder = (raw) => {
+        const entityType = raw.__edd_e__;
+        if (!entityType) {
+            return Effect.fail(new ValidationError({
+                entityType: "unknown",
+                operation: "collection.decode",
+                cause: "Item missing __edd_e__",
+            }));
+        }
+        const entry = entityByType.get(entityType);
+        if (!entry) {
+            return Effect.fail(new ValidationError({
+                entityType,
+                operation: "collection.decode",
+                cause: `Unknown entity type "${entityType}" in collection "${name}"`,
+            }));
+        }
+        return entry.entity._decodeRecord(raw).pipe(Effect.map((decoded) => ({
+            _entityKey: entry.key,
+            _entityType: entityType,
+            _decoded: decoded,
+        })));
+    };
+    // Build the query function
+    const buildQuery = (pkComposites, targetEntityTypes, decoder) => {
+        // Use the first entity to compose the PK (they share the same index pattern)
+        const firstEntity = entityEntries[0][1];
+        const indexDef = firstEntity.indexes[sharedIndexName];
+        const pkValue = KeyComposer.composePk(sharedSchema, firstEntity.entityType, indexDef, pkComposites);
+        return Query.make({
+            tableName: "",
+            indexName: sharedDynamoIndexName,
+            pkField: sharedPkField,
+            pkValue,
+            skField: sharedSkField,
+            entityTypes: targetEntityTypes,
+            decoder,
+            resolveTableName: firstEntity._tableTag.useSync((tc) => tc.name),
+        });
+    };
+    // Main query: returns grouped results
+    const queryAll = (pkComposites) => {
+        const groupDecoder = (raw) => collectionDecoder(raw);
+        // We need a custom decoder that groups results
+        // The Query will return flat items — we need to post-process into groups
+        // We'll use the collectionDecoder and the collect terminal will group them
+        const rawQuery = buildQuery(pkComposites, entityTypes, groupDecoder);
+        // Override with a custom decoder that produces the grouped result
+        let q = Query.make({
+            tableName: "",
+            indexName: sharedDynamoIndexName,
+            pkField: sharedPkField,
+            pkValue: rawQuery._state.pkValue,
+            skField: sharedSkField,
+            entityTypes,
+            resolveTableName: entityEntries[0][1]._tableTag.useSync((tc) => tc.name),
+            decoder: (raw) => {
+                // This decoder gets called per-item, but Query.collect collects all items
+                // We need to tag each item with its entity key so the caller can group
+                return collectionDecoder(raw);
+            },
+        });
+        // Clustered collections add begins_with SK condition on collection prefix
+        if (collectionType === "clustered" && collectionSkPrefix) {
+            q = q.pipe(Query.where({ beginsWith: collectionSkPrefix }));
+        }
+        return q;
+    };
+    // Entity selector functions
+    const selectors = {};
+    for (const [key, entity] of entityEntries) {
+        selectors[key] = (pkComposites) => {
+            const indexDef = entity.indexes[sharedIndexName];
+            const pkValue = KeyComposer.composePk(sharedSchema, entity.entityType, indexDef, pkComposites);
+            let q = Query.make({
+                tableName: "",
+                indexName: sharedDynamoIndexName,
+                pkField: sharedPkField,
+                pkValue,
+                skField: sharedSkField,
+                entityTypes: [entity.entityType],
+                decoder: (raw) => entity._decodeRecord(raw),
+                resolveTableName: entity._tableTag.useSync((tc) => tc.name),
+            });
+            // Clustered entity selectors add begins_with on the entity SK prefix.
+            // For sub-collections, the prefix uses the FULL hierarchy from root to
+            // the queried collection name, matching what composeSk writes at put time.
+            if (collectionType === "clustered" && collectionSkPrefix) {
+                const coll = indexDef.collection;
+                const hierarchy = Array.isArray(coll) ? coll.slice(0, coll.indexOf(name) + 1) : name;
+                const entitySkPrefix = DynamoSchema.composeClusteredSortKey(sharedSchema, hierarchy, entity.entityType, 1, [], { casing: indexDef.casing });
+                q = q.pipe(Query.where({ beginsWith: entitySkPrefix }));
+            }
+            return q;
+        };
+    }
+    return {
+        _tag: "Collection",
+        name,
+        entities,
+        query: queryAll,
+        ...selectors,
+    };
+};
+//# sourceMappingURL=Collection.js.map

package/dist/Collection.js.map

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

package/dist/Collections.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Collections — Explicit GSI access pattern definitions.
+ *
+ * `Collections.make()` defines ALL GSI-based access patterns. A collection owns
+ * the index definition (GSI name, PK/SK fields), shared PK composites, and each
+ * member entity specifies only its own SK composites.
+ *
+ * A collection can have one member (entity-specific access pattern) or multiple
+ * members (cross-entity access pattern). Entities only define their primary key —
+ * all secondary index definitions live in Collections.make().
+ *
+ * @module
+ */
+import type { Schema } from "effect";
+import type { IndexDefinition } from "./KeyComposer.js";
+/** @internal Minimal structural type for entities used in Collections. */
+export interface CollectionEntityLike {
+    readonly _tag: "Entity";
+    readonly model: Schema.Top;
+    readonly entityType: string;
+    readonly indexes: Record<string, IndexDefinition>;
+    readonly schemas: {
+        readonly recordSchema: Schema.Codec<any>;
+    };
+}
+/** A member binding within a collection: entity reference + SK composite attributes. */
+export interface CollectionMember<E extends CollectionEntityLike = CollectionEntityLike> {
+    readonly _tag: "CollectionMember";
+    readonly entity: E;
+    readonly sk: ReadonlyArray<string>;
+}
+/**
+ * Bind an entity to a collection with its SK composite attributes.
+ *
+ * @param entity - The entity to bind
+ * @param sk - SK composite attribute names for this entity within the collection
+ */
+export declare const member: <E extends CollectionEntityLike>(entity: E, sk: ReadonlyArray<string>) => CollectionMember<E>;
+/** Collection type (clustered or isolated). */
+export type CollectionType = "clustered" | "isolated";
+/** GSI index definition for a collection. */
+export interface CollectionIndex {
+    /** Physical GSI name (e.g., `"gsi3"`). */
+    readonly name: string;
+    /** PK field name (e.g., `"gsi3pk"`). */
+    readonly pk: string;
+    /** SK field name (e.g., `"gsi3sk"`). */
+    readonly sk: string;
+}
+/** Collection configuration passed to `Collections.make()`. */
+export interface CollectionConfig<TName extends string, TMembers extends Record<string, CollectionMember>> {
+    /** Collection name — used as SK prefix in clustered mode. Changing this breaks existing data. */
+    readonly name: TName;
+    /** Physical GSI definition: index name + PK/SK field names. */
+    readonly index: CollectionIndex;
+    /** Shared PK composite attributes (e.g., `["employee"]`). */
+    readonly composite: ReadonlyArray<string>;
+    /** Collection type: `"clustered"` (default) or `"isolated"`. */
+    readonly type?: CollectionType;
+    /** Named record mapping member names to `Collections.member()` declarations. */
+    readonly members: TMembers;
+}
+/**
+ * A Collection definition — carries index config, member types, and computed
+ * types for PK input, per-member SK composites, and grouped result.
+ */
+export interface Collection<TName extends string = string, TMembers extends Record<string, CollectionMember> = Record<string, CollectionMember>> {
+    readonly _tag: "Collection";
+    readonly name: TName;
+    readonly index: CollectionIndex;
+    readonly composite: ReadonlyArray<string>;
+    readonly type: CollectionType;
+    readonly members: TMembers;
+}
+/** Extract the model type from a CollectionMember's entity. */
+type MemberModelType<M extends CollectionMember> = M["entity"]["schemas"]["recordSchema"] extends Schema.Codec<infer A> ? A : unknown;
+/** Grouped collection result: member names → arrays of their model types. */
+export type CollectionResult<TMembers extends Record<string, CollectionMember>> = {
+    readonly [K in keyof TMembers]: Array<MemberModelType<TMembers[K]>>;
+};
+/** Extract the model fields type from a Schema.Top (Schema.Class or Schema.Struct). */
+type ModelFields<M extends Schema.Top> = M extends {
+    readonly fields: infer F;
+} ? F : never;
+/** Pick composite fields from the model, making them required. */
+export type CollectionPkInput<TMembers extends Record<string, CollectionMember>, TComposite extends ReadonlyArray<string>> = {
+    readonly [K in TComposite[number]]: PickFieldType<FirstMemberModel<TMembers>, K>;
+};
+/** Get the first member's model type (for PK composite type inference). */
+type FirstMemberModel<TMembers extends Record<string, CollectionMember>> = TMembers[keyof TMembers]["entity"]["model"];
+/** Pick a single field type from model fields. */
+type PickFieldType<M extends Schema.Top, K extends string> = ModelFields<M> extends Record<K, Schema.Top> ? Schema.Schema.Type<ModelFields<M>[K]> : string;
+/**
+ * Create a Collection definition with explicit GSI access pattern.
+ *
+ * @param config - Collection configuration
+ * @returns A Collection definition carrying typed member info
+ *
+ * @example
+ * ```ts
+ * const assignments = Collections.make({
+ *   name: "assignments",
+ *   index: { name: "gsi3", pk: "gsi3pk", sk: "gsi3sk" },
+ *   composite: ["employee"],
+ *   members: {
+ *     Employees: Collections.member(Employees, []),
+ *     Tasks: Collections.member(Tasks, ["project", "task"]),
+ *   },
+ * })
+ * ```
+ */
+export declare const make: <const TName extends string, const TMembers extends Record<string, CollectionMember>>(config: CollectionConfig<TName, TMembers>) => Collection<TName, TMembers>;
+/**
+ * Build the IndexDefinition for a member entity from collection config + member SK.
+ * Used by DynamoClient.make() to inject GSI indexes into entities.
+ *
+ * @internal
+ */
+export declare const buildMemberIndexDef: (collection: Collection, m: CollectionMember) => IndexDefinition;
+export {};
+//# sourceMappingURL=Collections.d.ts.map

package/dist/Collections.d.ts.map

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

package/dist/Collections.js

@@ -0,0 +1,121 @@
+/**
+ * Collections — Explicit GSI access pattern definitions.
+ *
+ * `Collections.make()` defines ALL GSI-based access patterns. A collection owns
+ * the index definition (GSI name, PK/SK fields), shared PK composites, and each
+ * member entity specifies only its own SK composites.
+ *
+ * A collection can have one member (entity-specific access pattern) or multiple
+ * members (cross-entity access pattern). Entities only define their primary key —
+ * all secondary index definitions live in Collections.make().
+ *
+ * @module
+ */
+import { getFields } from "./internal/EntitySchemas.js";
+/**
+ * Bind an entity to a collection with its SK composite attributes.
+ *
+ * @param entity - The entity to bind
+ * @param sk - SK composite attribute names for this entity within the collection
+ */
+export const member = (entity, sk) => ({
+    _tag: "CollectionMember",
+    entity,
+    sk,
+});
+// ---------------------------------------------------------------------------
+// Collections.make()
+// ---------------------------------------------------------------------------
+/**
+ * Create a Collection definition with explicit GSI access pattern.
+ *
+ * @param config - Collection configuration
+ * @returns A Collection definition carrying typed member info
+ *
+ * @example
+ * ```ts
+ * const assignments = Collections.make({
+ *   name: "assignments",
+ *   index: { name: "gsi3", pk: "gsi3pk", sk: "gsi3sk" },
+ *   composite: ["employee"],
+ *   members: {
+ *     Employees: Collections.member(Employees, []),
+ *     Tasks: Collections.member(Tasks, ["project", "task"]),
+ *   },
+ * })
+ * ```
+ */
+export const make = (config) => {
+    const memberEntries = Object.entries(config.members);
+    const collectionType = config.type ?? "isolated";
+    // --- Validation ---
+    // At least one member
+    if (memberEntries.length === 0) {
+        throw new Error(`Collection '${config.name}' requires at least 1 member`);
+    }
+    // No duplicate entity types
+    const entityTypes = new Set();
+    for (const [memberName, m] of memberEntries) {
+        if (entityTypes.has(m.entity.entityType)) {
+            throw new Error(`Entity type '${m.entity.entityType}' appears in multiple members of collection '${config.name}' (member '${memberName}')`);
+        }
+        entityTypes.add(m.entity.entityType);
+        // Validate PK composites exist on entity model
+        const fields = getModelFieldNames(m.entity.model);
+        for (const attr of config.composite) {
+            if (!fields.has(attr)) {
+                throw new Error(`Attribute '${attr}' not found on ${m.entity.entityType} model (collection '${config.name}', member '${memberName}')`);
+            }
+        }
+        // Validate SK composites exist on entity model
+        for (const attr of m.sk) {
+            if (!fields.has(attr)) {
+                throw new Error(`Attribute '${attr}' not found on ${m.entity.entityType} model (collection '${config.name}', member '${memberName}')`);
+            }
+        }
+    }
+    return {
+        _tag: "Collection",
+        name: config.name,
+        index: config.index,
+        composite: config.composite,
+        type: collectionType,
+        members: config.members,
+    };
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build the IndexDefinition for a member entity from collection config + member SK.
+ * Used by DynamoClient.make() to inject GSI indexes into entities.
+ *
+ * @internal
+ */
+export const buildMemberIndexDef = (collection, m) => ({
+    index: collection.index.name,
+    collection: collection.name,
+    type: collection.type,
+    pk: { field: collection.index.pk, composite: [...collection.composite] },
+    sk: {
+        field: collection.index.sk,
+        composite: [...m.sk],
+    },
+});
+/** @internal Get model field names (including ref ID fields). */
+const getModelFieldNames = (model) => {
+    try {
+        const fields = getFields(model);
+        const names = new Set(Object.keys(fields));
+        // Also add ref-derived ID fields (fieldNameId)
+        for (const fieldName of Object.keys(fields)) {
+            names.add(`${fieldName}Id`);
+        }
+        return names;
+    }
+    catch {
+        // If model doesn't have .fields, return empty set (validation will fail)
+        return new Set();
+    }
+};
+//# sourceMappingURL=Collections.js.map

package/dist/Collections.js.map

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