effect-dynamodb 0.1.0

package/dist/Entity.d.ts

@@ -0,0 +1,628 @@
+/**
+ * Entity — Binds a domain model to a Table with ElectroDB-style index definitions,
+ * system field configuration, unique constraints, and CRUD operations.
+ *
+ * Entity.make() returns a definition + operations namespace. The Entity object
+ * carries derived schemas for 7 type extractors (Model, Record, Input, Update,
+ * Key, Item, Marshalled).
+ */
+import type { AttributeValue } from "@aws-sdk/client-dynamodb";
+import { Effect, Schema, Stream } from "effect";
+import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
+import { type ConfiguredModel, type ExtractIdentifier } from "./DynamoModel.js";
+import * as DynamoSchema from "./DynamoSchema.js";
+import { ConditionalCheckFailed, ItemNotFound, OptimisticLockError, UniqueConstraintViolation, ValidationError } from "./Errors.js";
+import type { GsiConfig, IndexDefinition, KeyPart } from "./KeyComposer.js";
+import * as Query from "./Query.js";
+import type { TableConfig } from "./Table.js";
+export type { CascadeIndexConfig, RefValue, SoftDeleteConfig, TimestampFieldConfig, TimestampsConfig, UniqueConfig, UniqueConstraintDef, UniqueFieldsDef, VersionedConfig, } from "./internal/EntityConfig.js";
+export { type CascadeConfig, type CascadeTarget, type DecodeMode, type EntityBase, type EntityDelete, EntityDeleteImpl, EntityDeleteTypeId, type EntityGet, EntityGetImpl, type EntityGetOpts, type EntityOp, EntityOpTypeId, type EntityPut, EntityPutImpl, type EntityUpdate, EntityUpdateImpl, EntityUpdateTypeId, emptyUpdateState, type ReturnValuesMode, returnValuesMap, type UpdateState, } from "./internal/EntityOps.js";
+import { type EntityDelete, type EntityGet, type EntityPut, type EntityUpdate } from "./internal/EntityOps.js";
+export { add, append, asItem, asModel, asNative, asRecord, cascade, consistentRead, deleteFromSet, expectedVersion, pathAdd, pathAppend, pathDelete, pathIfNotExists, pathPrepend, pathRemove, pathSet, pathSubtract, project, remove, returnValues, set, subtract, } from "./internal/EntityCombinators.js";
+import type { CascadeIndexConfig, SoftDeleteConfig, TimestampsConfig, UniqueConfig, VersionedConfig } from "./internal/EntityConfig.js";
+/** A ref config object: the entity and optional cascade index config. */
+interface AnyRefValue {
+    readonly entity: Entity<any, any, any, any, any, any, any, any, any>;
+    readonly cascade?: CascadeIndexConfig;
+}
+import { type DerivedSchemas, type ResolvedSystemFields } from "./internal/EntitySchemas.js";
+import type { EntityInputType, EntityKeyType, EntityRecordType, EntityRefCreateType, EntityRefInputType, EntityRefUpdateType, EntityUpdateType, IndexPkInput, ModelType, PrimaryKeyComposites, RefErrors } from "./internal/EntityTypes.js";
+export type { IndexDefinition, KeyPart };
+/**
+ * An Entity binds a domain model to a DynamoDB Table with index definitions,
+ * system field configuration, unique constraints, and CRUD operations.
+ *
+ * Created via {@link make}. Returns a definition with descriptor builders.
+ * Table association and binding happen via `DynamoClient.make()`.
+ *
+ * @typeParam TModel - Effect Schema defining the domain model
+ * @typeParam TEntityType - Literal string discriminator stored as `__edd_e__`
+ * @typeParam TIndexes - Index definitions (primary + GSIs)
+ * @typeParam TTimestamps - Timestamp configuration
+ * @typeParam TVersioned - Optimistic locking configuration
+ * @typeParam TSoftDelete - Soft-delete configuration
+ * @typeParam TUnique - Unique constraint definitions
+ * @typeParam TIdentifier - Identifier field name (auto-generated, omitted from Create type)
+ */
+export interface Entity<TModel extends Schema.Top = Schema.Top, TEntityType extends string = string, TIndexes extends globalThis.Record<string, IndexDefinition> = globalThis.Record<string, IndexDefinition>, TTimestamps extends TimestampsConfig | undefined = TimestampsConfig | undefined, TVersioned extends VersionedConfig | undefined = VersionedConfig | undefined, TSoftDelete extends SoftDeleteConfig | undefined = SoftDeleteConfig | undefined, TUnique extends UniqueConfig | undefined = UniqueConfig | undefined, TRefs extends globalThis.Record<string, AnyRefValue> | undefined = undefined, TIdentifier extends string | undefined = undefined> {
+    readonly _tag: "Entity";
+    readonly model: TModel;
+    readonly entityType: TEntityType;
+    readonly indexes: TIndexes;
+    readonly timestamps: TTimestamps;
+    readonly versioned: TVersioned;
+    readonly softDelete: TSoftDelete;
+    readonly unique: TUnique;
+    readonly identifier: TIdentifier;
+    /** @internal Resolved ref metadata — used by cascade to inspect target entities */
+    readonly _resolvedRefs: ReadonlyArray<{
+        readonly fieldName: string;
+        readonly idFieldName: string;
+        readonly identifierField: string;
+        readonly refEntityType: string;
+    }>;
+    /** @internal Full decode pipeline: rename + date deser + schema decode. Used by Batch/Aggregate. */
+    readonly _decodeRecord: (raw: globalThis.Record<string, unknown>) => Effect.Effect<any, ValidationError>;
+    /** @internal Attach model class prototype to a decoded plain object (no-op for Schema.Struct models). */
+    readonly _attachPrototype: (decoded: any) => any;
+    /**
+     * @internal Configure the entity with table schema and tag.
+     * Called by DynamoClient.make() when binding entities to a table.
+     */
+    readonly _configure: (schema: DynamoSchema.DynamoSchema, tableTag: import("effect").Context.Service<TableConfig, TableConfig>) => void;
+    /**
+     * @internal Inject a GSI index definition into this entity.
+     * Called by Collections binding or DynamoClient.make() to add collection-owned indexes.
+     * The injected index becomes available to all entity operations (put, update, etc.)
+     * for key composition.
+     */
+    readonly _injectIndex: (name: string, def: IndexDefinition) => void;
+    /** @internal Injected DynamoSchema — available after _configure(). Used by cascade. */
+    readonly _schema: DynamoSchema.DynamoSchema;
+    /** @internal Injected TableConfig tag — available after _configure(). Used by cascade. */
+    readonly _tableTag: import("effect").Context.Service<TableConfig, TableConfig>;
+    /** Resolved system field names */
+    readonly systemFields: ResolvedSystemFields;
+    /** Derived schemas for type extraction */
+    readonly schemas: DerivedSchemas;
+    /**
+     * Typed input schema. Ref-aware: ref fields are replaced with branded ID fields.
+     * Use in HttpApiEndpoint payloads or for validation.
+     *
+     * @example
+     * ```ts
+     * HttpApiEndpoint.post("create", "/squads", {
+     *   payload: SquadSelections.inputSchema,
+     * })
+     * ```
+     */
+    readonly inputSchema: Schema.Codec<EntityRefInputType<TModel, TRefs>>;
+    /**
+     * Typed create schema. Input fields minus primary key composites — the common
+     * "create" payload where IDs are auto-generated.
+     *
+     * @example
+     * ```ts
+     * HttpApiEndpoint.post("create", "/teams", {
+     *   payload: Teams.createSchema,
+     *   success: Team,
+     * })
+     * ```
+     */
+    readonly createSchema: Schema.Codec<EntityRefCreateType<TModel, TIndexes, TRefs, TIdentifier>>;
+    /**
+     * Typed update schema. Partial fields minus primary key composites and immutable fields.
+     * Ref fields are replaced with optional branded ID fields.
+     */
+    readonly updateSchema: Schema.Codec<EntityRefUpdateType<TModel, TIndexes, TRefs>>;
+    /** Fetch an item by primary key. Returns a lazy {@link EntityGet} intermediate. */
+    readonly get: (key: EntityKeyType<TModel, TIndexes>) => EntityGet<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, ItemNotFound | DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /** Create or replace an item. Returns a lazy {@link EntityPut} intermediate. */
+    readonly put: (input: EntityRefInputType<TModel, TRefs>) => EntityPut<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, DynamoClientError | ValidationError | UniqueConstraintViolation | RefErrors<TRefs>, DynamoClient | TableConfig>;
+    /**
+     * Begin an update operation on an existing item. Returns a lazy {@link EntityUpdate} intermediate.
+     * Pipe to {@link set} to provide update fields and {@link expectedVersion} for optimistic locking.
+     */
+    readonly update: (key: EntityKeyType<TModel, TIndexes>) => EntityUpdate<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, EntityRefUpdateType<TModel, TIndexes, TRefs>, DynamoClientError | ItemNotFound | OptimisticLockError | UniqueConstraintViolation | ValidationError | RefErrors<TRefs>, DynamoClient | TableConfig>;
+    /** Delete an item by primary key. Returns a lazy {@link EntityDelete} intermediate. */
+    readonly delete: (key: EntityKeyType<TModel, TIndexes>) => EntityDelete<DynamoClientError | ItemNotFound, DynamoClient | TableConfig>;
+    /**
+     * Create a new item. Fails with `ConditionalCheckFailed` if an item with the same
+     * primary key already exists. Equivalent to `put(input)` with an `attribute_not_exists` condition.
+     */
+    readonly create: (input: EntityRefInputType<TModel, TRefs>) => EntityPut<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, DynamoClientError | ValidationError | UniqueConstraintViolation | ConditionalCheckFailed | RefErrors<TRefs>, DynamoClient | TableConfig>;
+    /**
+     * Update an existing item. Fails with `ConditionalCheckFailed` if the item doesn't exist.
+     * Equivalent to `update(key)` with an automatic `attribute_exists` condition on the PK field.
+     */
+    readonly patch: (key: EntityKeyType<TModel, TIndexes>) => EntityUpdate<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, EntityRefUpdateType<TModel, TIndexes, TRefs>, DynamoClientError | ItemNotFound | OptimisticLockError | UniqueConstraintViolation | ValidationError | ConditionalCheckFailed | RefErrors<TRefs>, DynamoClient | TableConfig>;
+    /**
+     * Delete an existing item. Fails with `ConditionalCheckFailed` if the item doesn't exist.
+     * Equivalent to `delete(key)` with an automatic `attribute_exists` condition on the PK field.
+     */
+    readonly deleteIfExists: (key: EntityKeyType<TModel, TIndexes>) => EntityDelete<DynamoClientError | ItemNotFound | ConditionalCheckFailed, DynamoClient | TableConfig>;
+    /**
+     * Create or update an item atomically. Uses DynamoDB UpdateItem with `if_not_exists()`
+     * for immutable fields and createdAt so they're only set on first creation.
+     * Version is incremented atomically: `if_not_exists(version, 0) + 1`.
+     * Returns the full record (ReturnValues: ALL_NEW).
+     *
+     * Does NOT support unique constraints or retain (cannot determine if item existed).
+     */
+    readonly upsert: (input: EntityRefInputType<TModel, TRefs>) => EntityPut<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, DynamoClientError | ValidationError | ItemNotFound | ConditionalCheckFailed | RefErrors<TRefs>, DynamoClient | TableConfig>;
+    /** Fetch a specific version snapshot by version number. */
+    readonly getVersion: (key: EntityKeyType<TModel, TIndexes>, version: number) => EntityGet<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, ItemNotFound | DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /** Query version history for an item. Returns a Query for piping with limit, reverse, collect. */
+    readonly versions: (key: EntityKeyType<TModel, TIndexes>) => Query.Query<EntityRecordType<TModel, TTimestamps, TVersioned>>;
+    /** Restore a soft-deleted item. Recomposes index keys and re-establishes unique sentinels. */
+    readonly restore: (key: EntityKeyType<TModel, TIndexes>) => EntityGet<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, ItemNotFound | DynamoClientError | ValidationError | UniqueConstraintViolation, DynamoClient | TableConfig>;
+    /** Permanently remove an item plus all version history and sentinels. */
+    readonly purge: (key: EntityKeyType<TModel, TIndexes>) => EntityDelete<DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /** Soft-deleted item accessors. */
+    readonly deleted: {
+        /** Get a specific soft-deleted item. */
+        readonly get: (key: EntityKeyType<TModel, TIndexes>) => EntityGet<ModelType<TModel>, EntityRecordType<TModel, TTimestamps, TVersioned>, ItemNotFound | DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+        /** List soft-deleted items within a partition. */
+        readonly list: (key: EntityKeyType<TModel, TIndexes>) => Query.Query<EntityRecordType<TModel, TTimestamps, TVersioned>>;
+    };
+    /**
+     * Set combinator pre-bound to this entity's update type.
+     *
+     * GSI all-or-none composites are enforced at runtime via `ValidationError`.
+     *
+     * @example
+     * ```typescript
+     * // data-last
+     * yield* Users.update({ userId: "u-1" }).pipe(
+     *   Users.set({ tenantId: "t-3", region: "us-east-1" }),
+     * )
+     *
+     * // data-first
+     * Entity.set(Users.update({ userId: "u-1" }), { tenantId: "t-3", region: "us-east-1" })
+     * ```
+     */
+    readonly set: {
+        (updates: EntityRefUpdateType<TModel, TIndexes, TRefs>): <A, Rec, U, E, R>(self: EntityUpdate<A, Rec, U, E, R>) => EntityUpdate<A, Rec, U, E, R>;
+        <A, Rec, U, E, R>(self: EntityUpdate<A, Rec, U, E, R>, updates: EntityRefUpdateType<TModel, TIndexes, TRefs>): EntityUpdate<A, Rec, U, E, R>;
+    };
+    /**
+     * Set expected version for optimistic locking.
+     * Entity-scoped for consistent pipe chains with {@link Entity.set}.
+     */
+    readonly expectedVersion: {
+        (version: number): <A, Rec, U, E, R>(self: EntityUpdate<A, Rec, U, E, R>) => EntityUpdate<A, Rec, U, E, R>;
+        <A, Rec, U, E, R>(self: EntityUpdate<A, Rec, U, E, R>, version: number): EntityUpdate<A, Rec, U, E, R>;
+    };
+    /** Index query accessors. Each non-primary index becomes a method that accepts PK composites and returns a {@link Query.Query}. */
+    readonly query: {
+        readonly [K in Exclude<keyof TIndexes, "primary">]: (pk: IndexPkInput<TModel, TIndexes, K, TRefs>) => Query.Query<ModelType<TModel>>;
+    };
+    /** Scan all items of this entity type. Returns a {@link Query.Query} that uses DynamoDB Scan. */
+    readonly scan: () => Query.Query<ModelType<TModel>>;
+    /**
+     * Build a condition expression combinator.
+     * Callback receives `(t, ops)` where `t` is a PathBuilder and `ops` provides comparison functions.
+     * Shorthand accepts a simple object for AND-equality conditions.
+     *
+     * @example
+     * ```typescript
+     * // Callback
+     * Teams.condition((t, { eq }) => eq(t.status, "active"))
+     * // Shorthand
+     * Teams.condition({ status: "active" })
+     * ```
+     */
+    readonly condition: {
+        (cb: (t: import("./internal/PathBuilder.js").PathBuilder<ModelType<TModel>, ModelType<TModel>>, ops: import("./internal/Expr.js").ConditionOps<ModelType<TModel>>) => import("./internal/Expr.js").Expr): <T extends EntityPut<any, any, any, any> | EntityUpdate<any, any, any, any, any> | EntityDelete<any, any>>(self: T) => T;
+        (shorthand: globalThis.Record<string, unknown>): <T extends EntityPut<any, any, any, any> | EntityUpdate<any, any, any, any, any> | EntityDelete<any, any>>(self: T) => T;
+    };
+    /**
+     * Build a filter expression for query/scan operations.
+     * Same API as `condition()` — callback or shorthand.
+     *
+     * @example
+     * ```typescript
+     * teams.collect(Teams.query.byAll(pk), Teams.filter((t, { gt }) => gt(t.wins, 10)))
+     * ```
+     */
+    readonly filter: {
+        (cb: (t: import("./internal/PathBuilder.js").PathBuilder<ModelType<TModel>, ModelType<TModel>>, ops: import("./internal/Expr.js").ConditionOps<ModelType<TModel>>) => import("./internal/Expr.js").Expr): <A>(self: Query.Query<A>) => Query.Query<A>;
+        (shorthand: globalThis.Record<string, unknown>): <A>(self: Query.Query<A>) => Query.Query<A>;
+    };
+    /**
+     * Build a select (projection) combinator for get/query/scan operations.
+     * Callback receives `t` — a PathBuilder. Returns an array of paths to project.
+     * String array shorthand for top-level only projections.
+     *
+     * @example
+     * ```typescript
+     * Teams.select((t) => [t.name, t.address.city])
+     * Teams.select(["name", "status"])
+     * ```
+     */
+    readonly select: {
+        (cb: (t: import("./internal/PathBuilder.js").PathBuilder<ModelType<TModel>, ModelType<TModel>>) => ReadonlyArray<import("./internal/PathBuilder.js").Path<ModelType<TModel>, any>>): (self: Query.Query<any>) => Query.Query<any>;
+        (attributes: ReadonlyArray<string>): (self: Query.Query<any>) => Query.Query<any>;
+    };
+}
+/**
+ * An Entity whose CRUD operations have `DynamoClient` and `TableConfig` already
+ * resolved, so all methods return `Effect<A, E, never>`.
+ *
+ * Created via {@link bind}. Use in service layers to avoid leaking infrastructure
+ * requirements through service method signatures.
+ *
+ * @example
+ * ```typescript
+ * export class TeamService extends Context.Service<TeamService>()("TeamService", {
+ *   make: Effect.gen(function* () {
+ *     const db = yield* DynamoClient.make({ entities: { Teams }, tables: { MainTable } })
+ *     const teams = db.entities.Teams
+ *     return {
+ *       get: (id: TeamId) => teams.get({ id }),           // R = never
+ *       create: (input) => teams.create({ ...input }),     // R = never
+ *       list: (filter) => teams.byAll(filter).collect(),  // R = never
+ *     }
+ *   }),
+ * }) {}
+ * ```
+ */
+/** Combinator that transforms a put/create/upsert operation. */
+export type PutCombinator<M> = (op: EntityPut<M, any, any, any>) => EntityPut<M, any, any, any>;
+/** Combinator that transforms an update/patch operation. */
+export type UpdateCombinator<M> = (op: EntityUpdate<M, any, any, any, any>) => EntityUpdate<M, any, any, any, any>;
+/** Combinator that transforms a delete operation. */
+export type DeleteCombinator = (op: EntityDelete<any, any>) => EntityDelete<any, any>;
+export interface BoundEntity<TModel extends Schema.Top, TIndexes extends globalThis.Record<string, IndexDefinition>, TRefs extends globalThis.Record<string, AnyRefValue> | undefined, TKey = EntityKeyType<TModel, TIndexes>> {
+    /** Fetch an item by primary key. Returns an Effect that resolves to the model type. */
+    readonly get: (key: TKey) => Effect.Effect<ModelType<TModel>, ItemNotFound | DynamoClientError | ValidationError, never>;
+    /** Create or replace an item. Accepts optional combinators (e.g. `Entity.condition(...)`). */
+    readonly put: (input: EntityRefInputType<TModel, TRefs>, ...combinators: ReadonlyArray<PutCombinator<ModelType<TModel>>>) => Effect.Effect<ModelType<TModel>, DynamoClientError | ValidationError | UniqueConstraintViolation | RefErrors<TRefs>, never>;
+    /** Create a new item. Fails if primary key already exists. Accepts optional combinators. */
+    readonly create: (input: EntityRefInputType<TModel, TRefs>, ...combinators: ReadonlyArray<PutCombinator<ModelType<TModel>>>) => Effect.Effect<ModelType<TModel>, DynamoClientError | ValidationError | UniqueConstraintViolation | ConditionalCheckFailed | RefErrors<TRefs>, never>;
+    /**
+     * Update an existing item. Applies combinators and returns an Effect.
+     *
+     * ```ts
+     * yield* teams.update({ id }, Entity.set(updates), Entity.expectedVersion(3))
+     * ```
+     */
+    readonly update: (key: TKey, ...combinators: ReadonlyArray<UpdateCombinator<ModelType<TModel>>>) => Effect.Effect<ModelType<TModel>, DynamoClientError | ItemNotFound | OptimisticLockError | UniqueConstraintViolation | ValidationError | RefErrors<TRefs>, never>;
+    /** Delete an item by primary key. Accepts optional combinators (e.g. `Entity.condition(...)`). */
+    readonly delete: (key: TKey, ...combinators: ReadonlyArray<DeleteCombinator>) => Effect.Effect<void, DynamoClientError | ItemNotFound, never>;
+    /**
+     * Create or update an item atomically. Uses DynamoDB UpdateItem with `if_not_exists()`
+     * for immutable fields and createdAt so they're only set on first creation.
+     * Accepts optional combinators.
+     */
+    readonly upsert: (input: EntityRefInputType<TModel, TRefs>, ...combinators: ReadonlyArray<PutCombinator<ModelType<TModel>>>) => Effect.Effect<ModelType<TModel>, DynamoClientError | ValidationError | ItemNotFound | ConditionalCheckFailed | RefErrors<TRefs>, never>;
+    /**
+     * Update an existing item. Fails with `ConditionalCheckFailed` if the item doesn't exist.
+     * Applies combinators and returns an Effect.
+     *
+     * ```ts
+     * yield* teams.patch({ id }, Entity.set(updates))
+     * ```
+     */
+    readonly patch: (key: TKey, ...combinators: ReadonlyArray<UpdateCombinator<ModelType<TModel>>>) => Effect.Effect<ModelType<TModel>, DynamoClientError | ItemNotFound | OptimisticLockError | UniqueConstraintViolation | ValidationError | ConditionalCheckFailed | RefErrors<TRefs>, never>;
+    /** Delete an existing item, fails if not found. Accepts optional combinators. */
+    readonly deleteIfExists: (key: TKey, ...combinators: ReadonlyArray<DeleteCombinator>) => Effect.Effect<void, DynamoClientError | ItemNotFound | ConditionalCheckFailed, never>;
+    /** Fetch a specific version snapshot by version number. */
+    readonly getVersion: (key: TKey, version: number) => Effect.Effect<ModelType<TModel>, ItemNotFound | DynamoClientError | ValidationError, never>;
+    /**
+     * List all version snapshots for an item as a fluent BoundQuery.
+     * Requires `versioned: { retain: true }` on the entity definition.
+     *
+     * ```ts
+     * const all = yield* db.entities.Users.versions({ userId: "u-1" }).collect()
+     * const last5 = yield* db.entities.Users
+     *   .versions({ userId: "u-1" })
+     *   .reverse()
+     *   .limit(5)
+     *   .collect()
+     * ```
+     */
+    readonly versions: (key: TKey) => import("./internal/BoundQuery.js").BoundQuery<ModelType<TModel>, never, ModelType<TModel>>;
+    /** Restore a soft-deleted item. */
+    readonly restore: (key: TKey) => Effect.Effect<ModelType<TModel>, ItemNotFound | DynamoClientError | ValidationError | UniqueConstraintViolation, never>;
+    /** Permanently remove an item plus all version history and sentinels. */
+    readonly purge: (key: TKey) => Effect.Effect<void, DynamoClientError | ValidationError, never>;
+    /** Soft-deleted item accessors. */
+    readonly deleted: {
+        /** Get a specific soft-deleted item. */
+        readonly get: (key: TKey) => Effect.Effect<ModelType<TModel>, ItemNotFound | DynamoClientError | ValidationError, never>;
+        /**
+         * List all soft-deleted items in this partition as a fluent BoundQuery.
+         * Requires `softDelete` on the entity definition.
+         *
+         * ```ts
+         * const tombstones = yield* db.entities.Employees.deleted
+         *   .list({ employeeId: "e-1" })
+         *   .collect()
+         * ```
+         */
+        readonly list: (key: TKey) => import("./internal/BoundQuery.js").BoundQuery<ModelType<TModel>, never, ModelType<TModel>>;
+    };
+    /**
+     * Execute a query and return a lazy Stream of items. Automatically paginates through all pages.
+     * Accepts optional query combinators (e.g. `Query.limit(...)`, `Query.reverse`).
+     *
+     * ```ts
+     * const stream = teams.paginate(Teams.query.byRole({ role: "admin" }), Query.limit(10))
+     * ```
+     */
+    readonly paginate: <A>(query: Query.Query<A>, ...combinators: ReadonlyArray<(q: Query.Query<A>) => Query.Query<A>>) => Stream.Stream<A, DynamoClientError | ValidationError, never>;
+    /**
+     * Execute a query and collect all pages into a single array.
+     * Accepts optional query combinators (e.g. `Query.limit(...)`, `Query.reverse`).
+     *
+     * ```ts
+     * const items = yield* teams.collect(Teams.query.byRole({ role: "admin" }), Query.limit(10))
+     * ```
+     */
+    readonly collect: <A>(query: Query.Query<A>, ...combinators: ReadonlyArray<(q: Query.Query<A>) => Query.Query<A>>) => Effect.Effect<Array<A>, DynamoClientError | ValidationError, never>;
+    /**
+     * Execute a single DynamoDB page and return a {@link Query.Page} with an opaque cursor.
+     * Use `Query.startFrom(cursor)` to iterate through subsequent pages.
+     * Accepts optional query combinators (e.g. `Query.limit(...)`, `Query.reverse`).
+     *
+     * ```ts
+     * const page = yield* teams.fetch(Teams.query.byRole({ role: "admin" }), Query.limit(25))
+     * if (page.cursor) {
+     *   const next = yield* teams.fetch(Teams.query.byRole({ role: "admin" }), Query.limit(25), Query.startFrom(page.cursor))
+     * }
+     * ```
+     */
+    readonly fetch: <A>(query: Query.Query<A>, ...combinators: ReadonlyArray<(q: Query.Query<A>) => Query.Query<A>>) => Effect.Effect<Query.Page<A>, DynamoClientError | ValidationError, never>;
+    /**
+     * Execute a single DynamoDB scan page and return a {@link Query.Page} with an opaque cursor.
+     * Convenience for `fetch(Entity.scan(), ...)`. Use `Query.startFrom(cursor)` for subsequent pages.
+     * Accepts optional query combinators (e.g. `Query.limit(...)`, `Query.filter(...)`).
+     *
+     * ```ts
+     * const page = yield* teams.scanFetch(Query.limit(25))
+     * if (page.cursor) {
+     *   const next = yield* teams.scanFetch(Query.limit(25), Query.startFrom(page.cursor))
+     * }
+     * ```
+     */
+    readonly scanFetch: (...combinators: ReadonlyArray<(q: Query.Query<ModelType<TModel>>) => Query.Query<ModelType<TModel>>>) => Effect.Effect<Query.Page<ModelType<TModel>>, DynamoClientError | ValidationError, never>;
+}
+/**
+ * Create a new Entity — binding a domain model to a Table with index definitions
+ * and optional system field configuration.
+ *
+ * @param config - Entity configuration
+ * @param config.model - Effect Schema class or struct defining the domain model
+ * @param config.entityType - Literal string discriminator stored as `__edd_e__`
+ * @param config.indexes - ElectroDB-style composite key definitions (must include `primary`)
+ * @param config.timestamps - Automatic `createdAt` / `updatedAt` fields
+ * @param config.versioned - Optimistic locking via auto-incrementing version field
+ * @param config.softDelete - Soft-delete behavior
+ * @param config.unique - Named unique constraints enforced via transaction sentinels
+ * @returns An {@link Entity} with typed CRUD operations and index query accessors
+ *
+ * @example
+ * ```typescript
+ * const Users = Entity.make({
+ *   model: User,
+ *   table: MainTable,
+ *   entityType: "User",
+ *   indexes: {
+ *     primary: { pk: { field: "pk", composite: ["userId"] }, sk: { field: "sk", composite: [] } },
+ *     byEmail: { index: "gsi1", pk: { field: "gsi1pk", composite: ["email"] }, sk: { field: "gsi1sk", composite: [] } },
+ *   },
+ *   timestamps: true,
+ *   versioned: true,
+ * })
+ * ```
+ */
+/** Compute the normalized indexes type from primaryKey + optional GSI configs. */
+type NormalizedIndexes<TPrimaryKey extends PrimaryKeyDef, TGsiIndexes extends globalThis.Record<string, GsiConfig>> = keyof TGsiIndexes extends never ? {
+    readonly primary: TPrimaryKey;
+} : {
+    readonly primary: TPrimaryKey;
+} & {
+    readonly [K in keyof TGsiIndexes & string]: IndexDefinition & {
+        readonly collection: TGsiIndexes[K]["collection"];
+        readonly pk: {
+            readonly composite: TGsiIndexes[K]["pk"]["composite"];
+        };
+        readonly sk: {
+            readonly composite: TGsiIndexes[K]["sk"]["composite"];
+        };
+    };
+};
+/** Primary key definition — used in the new `primaryKey` config form. */
+type PrimaryKeyDef = IndexDefinition & ({
+    readonly pk: {
+        readonly composite: readonly [string, ...string[]];
+    };
+} | {
+    readonly sk: {
+        readonly composite: readonly [string, ...string[]];
+    };
+});
+/**
+ * Create an Entity definition.
+ *
+ * `primaryKey` defines the table's primary key. `indexes` optionally defines GSI
+ * access patterns. GSIs with a `collection` property are auto-discovered as
+ * cross-entity collections by `DynamoClient.make()`.
+ *
+ * @example
+ * ```typescript
+ * const Tasks = Entity.make({
+ *   model: Task,
+ *   entityType: "Task",
+ *   primaryKey: {
+ *     pk: { field: "pk", composite: ["taskId"] },
+ *     sk: { field: "sk", composite: [] },
+ *   },
+ *   indexes: {
+ *     byProject: {
+ *       name: "gsi1",
+ *       pk: { field: "gsi1pk", composite: ["projectId"] },
+ *       sk: { field: "gsi1sk", composite: ["status"] },
+ *     },
+ *     assigned: {
+ *       collection: "assignments",
+ *       name: "gsi2",
+ *       pk: { field: "gsi2pk", composite: ["employee"] },
+ *       sk: { field: "gsi2sk", composite: ["project"] },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare const make: <TModel extends Schema.Top, const TEntityType extends string, const TPrimaryKey extends PrimaryKeyDef, const TGsiIndexes extends globalThis.Record<string, GsiConfig> = {}, const TTimestamps extends TimestampsConfig | undefined = undefined, const TVersioned extends VersionedConfig | undefined = undefined, const TSoftDelete extends SoftDeleteConfig | undefined = undefined, const TUnique extends UniqueConfig | undefined = undefined, const TRefs extends globalThis.Record<string, AnyRefValue> | undefined = undefined, const TAttrs extends {} = {}>(config: {
+    readonly model: TModel | ConfiguredModel<TModel, TAttrs>;
+    readonly entityType: TEntityType;
+    readonly primaryKey: TPrimaryKey;
+    readonly indexes?: TGsiIndexes;
+    readonly timestamps?: TTimestamps;
+    readonly versioned?: TVersioned;
+    readonly softDelete?: TSoftDelete;
+    readonly unique?: TUnique;
+    readonly refs?: TRefs;
+}) => Entity<TModel, TEntityType, NormalizedIndexes<TPrimaryKey, TGsiIndexes>, TTimestamps, TVersioned, TSoftDelete, TUnique, TRefs, ExtractIdentifier<ConfiguredModel<TModel, TAttrs>>>;
+/**
+ * Bind an Entity to resolved `DynamoClient` and `TableConfig` services.
+ * Returns a {@link BoundEntity} where all operations have `R = never`.
+ *
+ * @internal Used by `DynamoClient.make()` to bind entities.
+ */
+export declare const bind: <TModel extends Schema.Top, TEntityType extends string, TIndexes extends globalThis.Record<string, IndexDefinition>, TTimestamps extends TimestampsConfig | undefined, TVersioned extends VersionedConfig | undefined, TSoftDelete extends SoftDeleteConfig | undefined, TUnique extends UniqueConfig | undefined, TRefs extends globalThis.Record<string, AnyRefValue> | undefined, TIdentifier extends string | undefined>(entity: Entity<TModel, TEntityType, TIndexes, TTimestamps, TVersioned, TSoftDelete, TUnique, TRefs, TIdentifier>) => Effect.Effect<BoundEntity<TModel, TIndexes, TRefs>, never, DynamoClient | TableConfig>;
+export interface TransactableInfo {
+    readonly opType: "get" | "put" | "update" | "delete";
+    readonly entity: Entity;
+    readonly key?: globalThis.Record<string, unknown> | undefined;
+    readonly input?: globalThis.Record<string, unknown> | undefined;
+}
+/**
+ * Extract transactable metadata from an Entity operation intermediate.
+ * Returns undefined if the value is not a recognized entity operation.
+ */
+export declare const extractTransactable: (op: unknown) => TransactableInfo | undefined;
+/**
+ * Extract the pure model type from an Entity.
+ *
+ * `Entity.Model<typeof Users>` = `{ userId: string, email: string, ... }`
+ */
+export type Model<E extends {
+    readonly model: Schema.Top;
+}> = ModelType<E["model"]>;
+/**
+ * Extract the record type (model + system fields) from an Entity.
+ *
+ * `Entity.Record<typeof Users>` = model fields + createdAt, updatedAt, version
+ */
+export type Record<E extends {
+    readonly model: Schema.Top;
+    readonly timestamps: any;
+    readonly versioned: any;
+}> = EntityRecordType<E["model"], E["timestamps"], E["versioned"]>;
+/**
+ * Extract the input type from an Entity. Ref-aware: when refs are present,
+ * ref fields are replaced with `${field}Id: string`.
+ *
+ * `Entity.Input<typeof Users>` = model fields only
+ * `Entity.Input<typeof TeamPlayerSelection>` = `{ teamId: string, playerId: string, ... }`
+ */
+export type Input<E extends {
+    readonly model: Schema.Top;
+}> = E extends Entity<infer M extends Schema.Top, any, any, any, any, any, any, infer R, any> ? EntityRefInputType<M, R> : EntityInputType<E["model"]>;
+/**
+ * Extract the create type from an Entity — input fields minus the identifier.
+ * Uses the `identifier` config to determine which field to omit.
+ * Falls back to omitting all primary key composites when no identifier is set.
+ *
+ * `Entity.Create<typeof Teams>` = `{ name: string, gender: Gender, league: League }`
+ */
+export type Create<E extends {
+    readonly model: Schema.Top;
+    readonly indexes: any;
+}> = E extends Entity<infer M extends Schema.Top, any, infer I, any, any, any, any, infer R, infer Id> ? EntityRefCreateType<M, I, R, Id extends string ? Id : undefined> : Omit<EntityInputType<E["model"]>, PrimaryKeyComposites<E["indexes"]>>;
+/**
+ * Extract the update type from an Entity. Ref-aware: when refs are present,
+ * ref fields are replaced with optional `${field}Id?: string`.
+ *
+ * `Entity.Update<typeof Users>` = `{ email?: string, displayName?: string, ... }`
+ */
+export type Update<E extends {
+    readonly model: Schema.Top;
+    readonly indexes: any;
+}> = E extends Entity<infer M extends Schema.Top, any, infer I, any, any, any, any, infer R, any> ? EntityRefUpdateType<M, I, R> : EntityUpdateType<E["model"], E["indexes"]>;
+/**
+ * Extract the key type from an Entity.
+ * Primary index pk + sk composite attributes only.
+ *
+ * `Entity.Key<typeof Users>` = `{ userId: string }`
+ */
+export type Key<E extends {
+    readonly model: Schema.Top;
+    readonly indexes: any;
+}> = EntityKeyType<E["model"], E["indexes"]>;
+/**
+ * Extract the full DynamoDB item type (unmarshalled).
+ * Record + key attributes + __edd_e__.
+ *
+ * `Entity.Item<typeof Users>` = record + pk, sk, gsi1pk, etc. + __edd_e__
+ */
+export type Item<E extends {
+    readonly schemas: DerivedSchemas;
+}> = Schema.Schema.Type<E["schemas"]["itemSchema"]>;
+/**
+ * Marshalled DynamoDB item (AttributeValue format).
+ * For now, a simple record type. Full typing comes in Group 5.
+ */
+export type Marshalled<_E> = globalThis.Record<string, {
+    readonly S?: string;
+    readonly N?: string;
+    readonly BOOL?: boolean;
+    readonly NULL?: boolean;
+    readonly L?: ReadonlyArray<unknown>;
+    readonly M?: globalThis.Record<string, unknown>;
+}>;
+/** Minimal structural type for utility accessors (avoids Entity invariance issues). */
+interface EntityLike {
+    readonly indexes: globalThis.Record<string, IndexDefinition>;
+}
+/**
+ * Get the names of all primary key composite attributes for an entity.
+ */
+export declare const keyAttributes: (entity: EntityLike) => ReadonlyArray<string>;
+/**
+ * Get the names of all key field attributes (pk, sk, gsi1pk, etc.) for an entity.
+ */
+export declare const keyFieldNames: (entity: EntityLike) => ReadonlyArray<string>;
+/**
+ * Get the names of all composite attributes across all indexes.
+ */
+export declare const compositeAttributes: (entity: EntityLike) => ReadonlyArray<string>;
+/** Minimal structural type for schema accessors. */
+interface EntityWithSchemas {
+    readonly schemas: DerivedSchemas;
+    readonly _attachPrototype?: (decoded: any) => any;
+}
+/**
+ * Get the item schema for an entity.
+ *
+ * Returns a Schema that decodes unmarshalled DynamoDB items (plain JS objects
+ * from `Marshaller.fromAttributeMap`) into Entity.Record instances.
+ *
+ * Useful for consuming DynamoDB Streams or working with raw query results.
+ */
+export declare const itemSchema: (entity: EntityWithSchemas) => Schema.Codec<any>;
+/**
+ * Decode a marshalled DynamoDB item (AttributeValue format) into a typed Entity.Record.
+ *
+ * Unmarshalls the AttributeValue map to plain JS, then decodes via the entity's item schema.
+ * Useful for consuming DynamoDB Streams events or raw SDK responses.
+ *
+ * Returns an Effect that fails with `ValidationError` if the item doesn't match the schema.
+ */
+export declare const decodeMarshalledItem: (entity: EntityWithSchemas & {
+    readonly entityType: string;
+}, marshalledItem: globalThis.Record<string, AttributeValue>) => Effect.Effect<unknown, ValidationError>;
+//# sourceMappingURL=Entity.d.ts.map