effect-dynamodb 1.26.0 → 1.28.0

package/dist/EventStore.js

@@ -15,13 +15,20 @@
  * - Stream indexes (`makeStream({ indexes })`): sub-streams ordered by a key
  *   derived from each event, on an LSI or GSI, each projecting all of the
  *   event, all but its metadata, or only its keys — `readIndex`,
- *   `query.index`, and `indexDefinitions` for the `CreateTable` fragments
+ *   `query.index`, and `indexDefinitions` for the `CreateTable` fragments.
+ *   A GSI may derive its partition too, so several streams share one
+ *   partition of it, snapshots included (#149)
  * - `fold` / `foldFrom` helpers for state reconstruction
  * - Packed storage (`makeStream({ storedAs: { data } })`, `snapshot.storedAs`):
  *   event data and snapshot state as one JSON string, optionally compressed —
  *   read by the stored form, so a stream may mix native, JSON and compressed
  *   items; `measureAppend` / `measureSnapshot` for caller-side size planning,
  *   and `decodeStreamImage` for DynamoDB Streams records
+ * - Change-feed projections (#151): `projection` folds a stream into a
+ *   read-model entity in version order, filling gaps from the store instead of
+ *   waiting for delivery (`applyBatch`, `apply`, `catchUp`, `rebuild`,
+ *   `processBatch`, `bindProjection`), plus `decoder`, `eventFilterPattern`
+ *   and `batchResponse` for the change feed itself
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
  * DynamoClient, Marshaller).
@@ -35,8 +42,11 @@ import { isDispatchEligible, packedShape, packValue, unpackStoredSync, } from "@
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { Context, DateTime, Effect, Function, Option, Pipeable, Result, Schedule, Schema, } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
+import { ProjectionDecode, } from "./internal/EventProjection.js";
+import { eq } from "./internal/Expr.js";
 import { itemBytes, transactItemBytes } from "./internal/ItemSize.js";
 import { codecRequirements, currentRegistry, decodeImage, imageEntityType, runtimeCodecCheck, unregisteredCodecError, withRegistry, } from "./internal/Packed.js";
+import { createPathBuilder } from "./internal/PathBuilder.js";
 import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, transactItemTarget, } from "./internal/TransactWriteOps.js";
 import { diagnosedValidationError, diagnoseFailure, mergeKeyAttributes, withCause, } from "./internal/WriteDiagnosis.js";
 import { fromAttributeMap, toAttributeMap } from "./Marshaller.js";
@@ -145,21 +155,31 @@ const STREAM_INDEX_CONFIG_KEYS = [
     "pk",
     "sk",
     "key",
+    "partition",
+    "snapshot",
     "projection",
 ];
+/**
+ * @internal `pk = <streamPk>`: keeps one stream id's items in a partition of a
+ * stream index several streams (or stream ids) share (#149). The table's `pk`
+ * is projected into every index, whatever its projection.
+ */
+const streamPkFilter = (streamPk) => eq(createPathBuilder().pk, streamPk);
 /**
  * @internal Validate `makeStream({ indexes })` at definition time.
  *
  * @throws `[EDD-9063]` for a malformed entry (unknown `type`, a `gsi` without
- *   `pk`, an `lsi` with `pk`, an empty name, a `key` that is not a function,
- *   an unknown `projection`, a member the entry type does not declare — a
- *   misspelled `projection` would otherwise silently mean `"all"`).
+ *   `pk`, an `lsi` with `pk`, `partition` or `snapshot`, an empty name, a
+ *   `key` / `partition` / `snapshot` that is not a function, a `snapshot`
+ *   without `partition` or on a stream without a snapshot config, an unknown
+ *   `projection`, a member the entry type does not declare — a misspelled
+ *   `projection` would otherwise silently mean `"all"`).
  * @throws `[EDD-9064]` for an index attribute that collides with a
  *   stream-owned attribute.
  * @throws `[EDD-9065]` for two indexes sharing a physical index name or an
  *   attribute.
  */
-const resolveStreamIndexes = (streamName, indexes) => {
+const resolveStreamIndexes = (streamName, indexes, hasSnapshotConfig) => {
     if (indexes === undefined)
         return [];
     const fail = (code, message) => {
@@ -196,7 +216,30 @@ const resolveStreamIndexes = (streamName, indexes) => {
                 'declare type: "gsi".');
         }
         if (typeof entry.key !== "function") {
-            fail("EDD-9063", `index "${name}": key must be a function (event, version) => string | undefined.`);
+            fail("EDD-9063", `index "${name}": key must be a function (event, version, streamId) => string | undefined.`);
+        }
+        if (entry.partition !== undefined) {
+            if (type !== "gsi") {
+                fail("EDD-9063", `index "${name}": an "lsi" index is partitioned by the stream; only a "gsi" index ` +
+                    'derives its partition. Remove partition, or declare type: "gsi".');
+            }
+            if (typeof entry.partition !== "function") {
+                fail("EDD-9063", `index "${name}": partition must be a function (event, version, streamId) => string | undefined.`);
+            }
+        }
+        if (entry.snapshot !== undefined) {
+            if (typeof entry.snapshot !== "function") {
+                fail("EDD-9063", `index "${name}": snapshot must be a function (state, asOfVersion, streamId) => ` +
+                    "{ partition, key } | undefined.");
+            }
+            if (entry.partition === undefined) {
+                fail("EDD-9063", `index "${name}": snapshot requires partition — only a "gsi" index with a derived ` +
+                    "partition indexes the stream's snapshot.");
+            }
+            if (!hasSnapshotConfig) {
+                fail("EDD-9063", `index "${name}": snapshot requires the stream's snapshot config ` +
+                    "(makeStream({ snapshot: { schema } })); the stream writes no snapshot to index.");
+            }
         }
         const projection = (entry.projection ?? "all");
         if (projection !== "all" && projection !== "withoutMetadata" && projection !== "keys") {
@@ -233,7 +276,11 @@ const resolveStreamIndexes = (streamName, indexes) => {
             pk,
             sk,
             projection,
+            partition: entry.partition === undefined ? "stream" : "derived",
+            snapshot: entry.snapshot !== undefined,
             key: entry.key,
+            derivePartition: entry.partition,
+            snapshotEntry: entry.snapshot,
         });
     }
     return resolved;
@@ -302,6 +349,24 @@ const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
  * attach it; a hand-built stream object falls back to joining the id's values.
  */
 const StreamIdFormatter = Symbol.for("effect-dynamodb/EventStream/StreamIdFormatter");
+/** @internal {@link EventStream.parseStreamId}, shared by `makeStream` and `bind`. */
+const parseStreamIdWith = (streamName, fields, streamId) => {
+    const parts = fields.length === 1 ? [streamId] : streamId.split("#");
+    if (parts.length !== fields.length) {
+        return Effect.fail(new ValidationError({
+            entityType: `${streamName.toLowerCase()}.event`,
+            operation: "EventStore.parseStreamId",
+            cause: `Stream id ${JSON.stringify(streamId)} has ${parts.length} "#"-separated parts, but ` +
+                `the stream id has ${fields.length} fields (${fields.join(", ")}): a value containing ` +
+                `"#" makes the id ambiguous.`,
+        }));
+    }
+    const id = {};
+    fields.forEach((field, i) => {
+        id[field] = parts[i];
+    });
+    return Effect.succeed(id);
+};
 /** @internal */
 const formatStreamIdOf = (stream, streamId) => {
     const formatter = stream[StreamIdFormatter];
@@ -430,11 +495,20 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  * `indexes` declares sub-streams ordered by a key derived from each event
  * (#140), on a local (default) or global secondary index. `append` writes each
  * event's derived key (and, for a GSI, the stream's partition key) on the
- * event item; snapshots and idempotency sentinels never carry them, so they
- * are never in an index. Read with {@link EventStream.readIndex} or
- * `query.index`, and create the indexes with {@link indexDefinitions}. Each
- * index's `projection` (default `"all"`) sets what it copies from each event
- * and how it is read — see {@link StreamIndexProjection}.
+ * event item. Idempotency sentinels never carry them; snapshots carry an
+ * entry only in a GSI that derives its partition and declares `snapshot`.
+ * Read with {@link EventStream.readIndex} or `query.index`, and create the
+ * indexes with {@link indexDefinitions}. Each index's `projection` (default
+ * `"all"`) sets what it copies from each event and how it is read — see
+ * {@link StreamIndexProjection}.
+ *
+ * A GSI's `partition` (#149) derives the partition from the stream id and the
+ * event instead, stored raw, so several streams declaring the same GSI write
+ * one partition of it — an order's line, payment and shipment streams under
+ * `ORDER#<orderId>`, read by one query — and its `snapshot` puts each stream's
+ * snapshot item in that partition too, in the same `Put` (so an inline
+ * snapshot enters the index in the append's own transaction). See
+ * {@link GlobalStreamIndexConfig}.
  *
  * Index attributes are written only at append time and events are never
  * rewritten. Declaring an index on a stream that already holds events, or
@@ -446,6 +520,36 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  *
  * @example
  * ```typescript
+ * // Lines and payments of an order share `gsi1` under `ORDER#<orderId>`.
+ * const OrderLines = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "OrderLine",
+ *   events: [LineAdded, LineRemoved],
+ *   streamId: { composite: ["orderId", "lineId"] },
+ *   snapshot: { schema: LineState, mode: "inline" },
+ *   indexes: {
+ *     byOrder: {
+ *       type: "gsi",
+ *       index: "gsi1",
+ *       pk: "gsi1pk",
+ *       sk: "gsi1sk",
+ *       partition: (_event, _version, streamId) => `ORDER#${streamId.orderId}`,
+ *       key: (_event, version, streamId) => `LINE#${streamId.lineId}#EVT#${pad(version)}`,
+ *       snapshot: (_state, _asOfVersion, streamId) => ({
+ *         partition: `ORDER#${streamId.orderId}`,
+ *         key: `LINE#${streamId.lineId}#STATE`,
+ *       }),
+ *     },
+ *   },
+ * })
+ *
+ * const lineEvents = yield* OrderLines.readIndex("byOrder", { orderId, lineId }, {
+ *   partition: `ORDER#${orderId}`,
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
  * const Entries = EventStore.makeStream({
  *   table: EventsTable,
  *   streamName: "Ledger",
@@ -470,10 +574,12 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  * @throws `[EDD-9062]` when `snapshot.mode` is neither `"after-append"` nor
  *   `"inline"`.
  * @throws `[EDD-9063]` for a malformed index: a `type` other than `"lsi"` /
- *   `"gsi"`, a `gsi` without `pk`, an `lsi` with `pk`, an empty `index` / `sk`
- *   / `pk`, a `key` that is not a function, a `projection` other than
- *   `"all"` / `"withoutMetadata"` / `"keys"`, or a member an index entry does
- *   not declare (such as a misspelled `projection`, also a type error).
+ *   `"gsi"`, a `gsi` without `pk`, an `lsi` with `pk`, `partition` or
+ *   `snapshot`, an empty `index` / `sk` / `pk`, a `key` / `partition` /
+ *   `snapshot` that is not a function, a `snapshot` without `partition` or on
+ *   a stream without a `snapshot` config, a `projection` other than `"all"` /
+ *   `"withoutMetadata"` / `"keys"`, or a member an index entry does not
+ *   declare (such as a misspelled `projection`, also a type error).
  * @throws `[EDD-9064]` when an index attribute is one the stream writes itself
  *   (`pk`, `sk`, `__edd_e__`, `streamId`, `version`, `eventType`, `data`,
  *   `metadata`, `timestamp`, `asOfVersion`, `state`, `commandId`, or the
@@ -578,7 +684,7 @@ export const makeStream = (config) => {
             },
         ];
     // Stream indexes (#140) — validated at definition time (EDD-9063..9065).
-    const streamIndexes = resolveStreamIndexes(config.streamName, config.indexes);
+    const streamIndexes = resolveStreamIndexes(config.streamName, config.indexes, snapshot !== undefined);
     const indexSettings = {};
     for (const idx of streamIndexes) {
         indexSettings[idx.name] = {
@@ -587,8 +693,12 @@ export const makeStream = (config) => {
             pk: idx.pk,
             sk: idx.sk,
             projection: idx.projection,
+            partition: idx.partition,
+            snapshot: idx.snapshot,
         };
     }
+    /** The indexes that hold the stream's snapshot (#149). */
+    const snapshotIndexes = streamIndexes.filter((idx) => idx.snapshotEntry !== undefined);
     /** Every attribute the indexes write on an event item. */
     const indexAttributes = streamIndexes.flatMap((idx) => idx.type === "gsi" ? [idx.pk, idx.sk] : [idx.sk]);
     // Build union schema from event schemas for decoding
@@ -719,34 +829,61 @@ export const makeStream = (config) => {
     // append
     // ---------------------------------------------------------------------------
     /**
-     * An event's key in a stream index (#140): a string, or `undefined` to
-     * leave the event out. Another type, or a `key` that throws, is a
-     * `ValidationError`, raised before anything is written. DynamoDB's own
-     * rules on a key — not empty, at most 1024 bytes for a sort key — are not
-     * pre-checked: DynamoDB rejects the append and the rejection is diagnosed,
-     * naming the index and event (see `sendAppendTransaction`).
+     * One value an index function derives for an item (#140, #149): an event's
+     * `key` or `partition`, a string or `undefined` to leave the item out.
+     * Another type, or a function that throws, is a `ValidationError`, raised
+     * before anything is written. DynamoDB's own rules on a key — not empty, at
+     * most 1024 bytes for a sort key and 2048 for a partition key — are not
+     * pre-checked: DynamoDB rejects the write and the rejection is diagnosed,
+     * naming the index and the item (see `sendAppendTransaction`).
      */
-    const deriveIndexKey = (idx, event, version) => Effect.try({
-        try: () => idx.key(event, version),
+    const deriveIndexValue = (idx, what, subject, derive) => Effect.try({
+        try: derive,
         catch: (cause) => new ValidationError({ entityType, operation: "EventStore.append.indexes", cause }),
     }).pipe(Effect.flatMap((derived) => {
         if (derived === undefined)
             return Effect.succeed(undefined);
-        const refuse = (problem) => Effect.fail(new ValidationError({
-            entityType,
-            operation: "EventStore.append.indexes",
-            cause: `The key of index "${idx.name}" for the event at version ${version} ${problem}. ` +
-                "Nothing was written.",
-        }));
         // A string, or the event is not indexed: what the stream's own key
         // contract means, which DynamoDB cannot see (a number would be sent
         // as `N`). An empty string is DynamoDB's to reject, and is diagnosed
         // from its rejection, naming the index and the event (#144).
         if (typeof derived !== "string") {
-            return refuse(`must be a string or undefined; received ${String(derived)}`);
+            return Effect.fail(new ValidationError({
+                entityType,
+                operation: "EventStore.append.indexes",
+                cause: `The ${what} of index "${idx.name}" for ${subject} must be a string or ` +
+                    `undefined; received ${String(derived)}. Nothing was written.`,
+            }));
         }
         return Effect.succeed(derived);
     }));
+    /**
+     * The snapshot's entry in a stream index (#149): its partition and key, or
+     * `undefined` to leave it out. Anything but an object of two strings, or an
+     * entry function that throws, is a `ValidationError` before anything is
+     * written; DynamoDB's rules on the values are its own, as for events.
+     */
+    const deriveSnapshotEntry = (idx, entry, state, streamId, asOfVersion, operation) => Effect.try({
+        try: () => entry(state, asOfVersion, streamId),
+        catch: (cause) => new ValidationError({ entityType: snapshotEntityType, operation, cause }),
+    }).pipe(Effect.flatMap((derived) => {
+        if (derived === undefined)
+            return Effect.succeed(undefined);
+        const { partition, key } = typeof derived === "object" && derived !== null
+            ? derived
+            : { partition: undefined, key: undefined };
+        if (typeof partition !== "string" || typeof key !== "string") {
+            return Effect.fail(new ValidationError({
+                entityType: snapshotEntityType,
+                operation,
+                cause: `The snapshot entry of index "${idx.name}" at version ${asOfVersion} must be ` +
+                    "{ partition: string, key: string } or undefined; received " +
+                    `${derived !== null && typeof derived === "object" ? JSON.stringify(derived) : String(derived)}. ` +
+                    "Nothing was written.",
+            }));
+        }
+        return Effect.succeed({ partition, key });
+    }));
     /**
      * Encode snapshot state to wire form through the state schema, with the
      * same `decode → encode` fallback as events and metadata. A structurally
@@ -852,48 +989,80 @@ export const makeStream = (config) => {
     };
     /**
      * A diagnosed rejection of an append (#144) other than its item count. An
-     * over-long (or empty) stream-index sort key OF AN EVENT — the value the
-     * index's `key` function returned — is named by its index and event, as
-     * the `indexes` option reports its other key problems. Only the event puts
-     * carry stream-index keys: an additional item writing the same physical
-     * attribute (single-table designs share `gsi1sk` and the like) is its own
-     * entity's key, and is named as any other item.
+     * over-long (or empty) stream-index key OF AN EVENT OR THE INLINE SNAPSHOT
+     * — a value an index function returned — is named by its index and item,
+     * as the `indexes` option reports its other key problems (see
+     * {@link indexKeyError}). Only the stream's own items carry stream-index
+     * keys: an additional item writing the same physical attribute
+     * (single-table designs share `gsi1sk` and the like) is its own entity's
+     * key, and is named as any other item.
      */
     const appendLimitError = (diagnosis, original, tx) => {
-        if ((diagnosis._tag === "KeyTooLong" && diagnosis.kind === "sort") ||
-            diagnosis._tag === "EmptyKey") {
+        if (diagnosis._tag === "KeyTooLong" || diagnosis._tag === "EmptyKey") {
             const position = tx.targets().indexOf(diagnosis.target);
             const isEvent = position >= tx.guardCount && position < tx.guardCount + tx.eventCount;
-            const idx = isEvent
-                ? streamIndexes.find((candidate) => candidate.sk === diagnosis.attribute)
+            const isSnapshot = position >= 0 && position === tx.snapshotIndex;
+            const named = isEvent || isSnapshot
+                ? indexKeyError(diagnosis, original, isSnapshot, "the append", "EventStore.append.indexes")
                 : undefined;
-            if (idx !== undefined) {
-                return new ValidationError({
-                    entityType,
-                    operation: "EventStore.append.indexes",
-                    cause: withCause(`The key of index "${idx.name}" for ${diagnosis.target.source} ` +
-                        (diagnosis._tag === "KeyTooLong"
-                            ? `is ${diagnosis.bytes} bytes, longer than DynamoDB's 1024-byte limit for a ` +
-                                "sort key."
-                            : "is an empty string, which DynamoDB does not accept as a key value; the " +
-                                "key function must return a non-empty string, or undefined to leave the " +
-                                "event out of the index.") +
-                        " DynamoDB rejected the append. Nothing was written.", original),
-                });
-            }
+            if (named !== undefined)
+                return named;
         }
         return diagnosedValidationError(diagnosis, original, {
             operation: "EventStore.append",
             entityType,
         });
     };
+    /**
+     * An over-long or empty key value in a stream-index attribute of an event
+     * or snapshot item, named by its index and item, or `undefined` when the
+     * attribute is not one the item's indexes derive. An event carries each
+     * index's `key` (and a derived `partition`); a snapshot, each snapshot
+     * index's entry. A stream-scoped GSI's partition is the stream's own key,
+     * which no function returned: it is named as any key.
+     */
+    const indexKeyError = (diagnosis, original, isSnapshot, request, operation) => {
+        const candidates = isSnapshot ? snapshotIndexes : streamIndexes;
+        const kind = diagnosis._tag === "KeyTooLong"
+            ? diagnosis.kind
+            : candidates.some((idx) => idx.sk === diagnosis.attribute)
+                ? "sort"
+                : "partition";
+        const idx = candidates.find((candidate) => kind === "sort"
+            ? candidate.sk === diagnosis.attribute
+            : candidate.partition === "derived" && candidate.pk === diagnosis.attribute);
+        if (idx === undefined)
+            return undefined;
+        const value = isSnapshot
+            ? `The snapshot entry's ${kind === "sort" ? "key" : "partition"}`
+            : `The ${kind === "sort" ? "key" : "partition"}`;
+        const leaveOut = isSnapshot
+            ? "the snapshot function must return non-empty strings, or undefined to leave the " +
+                "snapshot out of the index."
+            : `the ${kind === "sort" ? "key" : "partition"} function must return a non-empty ` +
+                "string, or undefined to leave the event out of the index.";
+        return new ValidationError({
+            entityType: isSnapshot ? snapshotEntityType : entityType,
+            operation,
+            cause: withCause(`${value} of index "${idx.name}" for ${diagnosis.target.source} ` +
+                (diagnosis._tag === "KeyTooLong"
+                    ? `is ${diagnosis.bytes} bytes, longer than DynamoDB's ` +
+                        `${kind === "sort" ? "1024-byte limit for a sort" : "2048-byte limit for a partition"} key.`
+                    : `is an empty string, which DynamoDB does not accept as a key value; ${leaveOut}`) +
+                ` DynamoDB rejected ${request}. Nothing was written.`, original),
+        });
+    };
     /**
      * The snapshot item for `state` at `asOfVersion`: the state encoded through
      * the state schema, then packed per `snapshot.storedAs` (#147) — so every
-     * size measured afterwards is the stored size. Shared by `writeSnapshot`,
-     * the inline snapshot of `append`, and `measureSnapshot` / `measureAppend`.
+     * size measured afterwards is stored bytes — with its entry in each index
+     * that holds snapshots (#149). Shared by `writeSnapshot`, the inline
+     * snapshot of `append`, and `measureSnapshot` / `measureAppend`.
+     *
+     * `eventPartitions` — the partition the append's events have in each
+     * index, by index name — is what the inline snapshot's entry must match.
      */
-    const buildSnapshotItem = (pk, streamIdStr, state, asOfVersion, now, operation) => Effect.gen(function* () {
+    const buildSnapshotItem = (streamId, state, asOfVersion, now, operation, eventPartitions) => Effect.gen(function* () {
         const encoded = yield* encodeSnapshotState(state, operation);
         const stored = stateStoredAs === undefined
             ? encoded
@@ -902,15 +1071,36 @@ export const makeStream = (config) => {
                 attribute: "state",
                 operation: `${operation}.packed`,
             });
-        return toAttributeMap({
-            pk,
+        const item = {
+            pk: composeStreamPk(streamId),
             sk: snapshotSk,
             __edd_e__: snapshotEntityType,
-            streamId: streamIdStr,
+            streamId: composeStreamIdString(streamId),
             asOfVersion,
             state: stored,
             timestamp: now,
-        });
+        };
+        // The snapshot's index entries (#149), stored raw on the item itself,
+        // so they are written by the same `Put` and count towards its size.
+        for (const idx of snapshotIndexes) {
+            const entry = yield* deriveSnapshotEntry(idx, idx.snapshotEntry, state, streamId, asOfVersion, operation);
+            if (entry === undefined)
+                continue;
+            const events = eventPartitions?.get(idx.name);
+            if (events !== undefined && events.partition !== entry.partition) {
+                return yield* new ValidationError({
+                    entityType: snapshotEntityType,
+                    operation,
+                    cause: `The inline snapshot's partition in index "${idx.name}" is ` +
+                        `${JSON.stringify(entry.partition)}, but ${events.subject} has ` +
+                        `${JSON.stringify(events.partition)}: an append's events and its inline snapshot ` +
+                        "must be in the same partition of an index. Nothing was written.",
+                });
+            }
+            item[idx.pk] = entry.partition;
+            item[idx.sk] = entry.key;
+        }
+        return toAttributeMap(item);
     });
     /**
      * The stream's own items of an append — everything but the caller's
@@ -1021,6 +1211,10 @@ export const makeStream = (config) => {
         else if (options?.metadata !== undefined) {
             encodedMetadata = options.metadata;
         }
+        // The partition the events have in each index that derives one (#149),
+        // by index name, with the first event that has it: the events and the
+        // inline snapshot of one append must agree.
+        const eventPartitions = new Map();
         // Build the event puts — one Put per event, each with attribute_not_exists(pk).
         // Events are encoded to wire form through their schema (codec symmetry
         // with the read path, which decodes through the same schema), so this is
@@ -1079,15 +1273,39 @@ export const makeStream = (config) => {
                 item.metadata = itemMetadata;
             }
             // Stream indexes (#140): the derived key, stored raw, and for a
-            // GSI the stream's partition key. The attributes are part of the
-            // event item itself, so they count towards the size checks.
+            // GSI the stream's partition key — or the derived partition, raw
+            // too (#149). The attributes are part of the event item itself,
+            // so they count towards the size checks. Both functions run for
+            // every event, so each one's contract is checked on every event.
+            const subject = `the event at version ${version}`;
             for (const idx of streamIndexes) {
-                const derived = yield* deriveIndexKey(idx, event, version);
-                if (derived === undefined)
+                const derived = yield* deriveIndexValue(idx, "key", subject, () => idx.key(event, version, streamId));
+                let partition = pk;
+                if (idx.derivePartition !== undefined) {
+                    const derivePartition = idx.derivePartition;
+                    partition = yield* deriveIndexValue(idx, "partition", subject, () => derivePartition(event, version, streamId));
+                    if (partition !== undefined) {
+                        const first = eventPartitions.get(idx.name);
+                        if (first === undefined) {
+                            eventPartitions.set(idx.name, { partition, subject });
+                        }
+                        else if (first.partition !== partition) {
+                            return yield* new ValidationError({
+                                entityType,
+                                operation: "EventStore.append.indexes",
+                                cause: `The partition of index "${idx.name}" for ${subject} is ` +
+                                    `${JSON.stringify(partition)}, but ${first.subject} has ` +
+                                    `${JSON.stringify(first.partition)}: every event of one append must be ` +
+                                    "in the same partition of an index. Nothing was written.",
+                            });
+                        }
+                    }
+                }
+                if (derived === undefined || partition === undefined)
                     continue;
                 item[idx.sk] = derived;
                 if (idx.type === "gsi")
-                    item[idx.pk] = pk;
+                    item[idx.pk] = partition;
             }
             return {
                 Put: {
@@ -1136,7 +1354,7 @@ export const makeStream = (config) => {
             snapshotPut = {
                 Put: {
                     TableName: tableName,
-                    Item: yield* buildSnapshotItem(pk, streamIdStr, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot"),
+                    Item: yield* buildSnapshotItem(streamId, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions),
                 },
             };
         }
@@ -1215,6 +1433,7 @@ export const makeStream = (config) => {
             if (sentinelPut !== undefined) {
                 pushStreamItem(sentinelPut, entityType, "the idempotency sentinel");
             }
+            const snapshotIndex = snapshotPut === undefined ? -1 : items.length;
             if (snapshotPut !== undefined) {
                 pushStreamItem(snapshotPut, snapshotEntityType, "the inline snapshot");
             }
@@ -1227,6 +1446,7 @@ export const makeStream = (config) => {
                 eventCount: eventItems.length,
                 additional,
                 sentinelIndex,
+                snapshotIndex,
                 expectedVersion,
             };
         };
@@ -1289,7 +1509,7 @@ export const makeStream = (config) => {
         if (snapshot === undefined)
             return yield* snapshotUnavailable("measureSnapshot");
         const now = DateTime.formatIso(yield* DateTime.now);
-        const item = yield* buildSnapshotItem(composeStreamPk(streamId), composeStreamIdString(streamId), state, asOfVersion, now, "EventStore.measureSnapshot");
+        const item = yield* buildSnapshotItem(streamId, state, asOfVersion, now, "EventStore.measureSnapshot");
         return itemBytes(item);
     });
     // ---------------------------------------------------------------------------
@@ -1336,8 +1556,11 @@ export const makeStream = (config) => {
         // Versions are integers, so the inclusive lower bound `afterVersion + 1`
         // is exactly the old exclusive `#sk > eventSk(afterVersion)`. The upper
         // bound keeps the snapshot item (which sorts after every event) out of the
-        // scanned range.
-        const query = withReadOptions(buildEventsQuery(streamId).pipe(Query.where({ between: [composeEventSk(afterVersion + 1), maxEventSk] })), options);
+        // scanned range; `toVersion` narrows it to the versions wanted.
+        const upper = options?.toVersion === undefined ? maxEventSk : composeEventSk(options.toVersion);
+        if (options?.toVersion !== undefined && options.toVersion <= afterVersion)
+            return [];
+        const query = withReadOptions(buildEventsQuery(streamId).pipe(Query.where({ between: [composeEventSk(afterVersion + 1), upper] })), options);
         return yield* Query.collect(query);
     });
     // ---------------------------------------------------------------------------
@@ -1379,7 +1602,7 @@ export const makeStream = (config) => {
         const now = DateTime.formatIso(yield* DateTime.now);
         // Packed per `snapshot.storedAs` (#147): the diagnosis below measures
         // the stored bytes.
-        const item = yield* buildSnapshotItem(composeStreamPk(streamId), composeStreamIdString(streamId), state, asOfVersion, now, "EventStore.writeSnapshot");
+        const item = yield* buildSnapshotItem(streamId, state, asOfVersion, now, "EventStore.writeSnapshot");
         const put = {
             TableName: tableName,
             Item: item,
@@ -1397,11 +1620,19 @@ export const makeStream = (config) => {
                 item: { Put: put },
                 target: () => transactItemTarget({ Put: put }, tableName, ["pk", "sk"], snapshotEntityType, "the snapshot"),
             }),
-            keys: () => ({ partition: ["pk"], sort: ["sk"] }),
-            rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, {
-                operation: "EventStore.writeSnapshot",
-                entityType: snapshotEntityType,
+            keys: () => ({
+                partition: ["pk", ...snapshotIndexes.map((idx) => idx.pk)],
+                sort: ["sk", ...snapshotIndexes.map((idx) => idx.sk)],
             }),
+            // A snapshot index entry's empty or over-long value (#149) is named
+            // by its index, as an inline snapshot's is.
+            rewrite: (diagnosis, original) => (diagnosis._tag === "KeyTooLong" || diagnosis._tag === "EmptyKey"
+                ? indexKeyError(diagnosis, original, true, "the snapshot", "EventStore.writeSnapshot")
+                : undefined) ??
+                diagnosedValidationError(diagnosis, original, {
+                    operation: "EventStore.writeSnapshot",
+                    entityType: snapshotEntityType,
+                }),
         }));
     });
     /**
@@ -1591,15 +1822,44 @@ export const makeStream = (config) => {
     // Stream indexes — query.index / readIndex (#140)
     // ---------------------------------------------------------------------------
     /**
-     * A query of one stream index, scoped to the stream's partition: the LSI
-     * shares the table's `pk`; a GSI's `pk` attribute carries the same value.
-     * No sort-key condition — the index holds only this stream's indexed events
-     * under that key; `Query.where` narrows the derived-key range.
+     * @internal Why `partition` cannot be passed for index `name`, or
+     * `undefined` when it can: required (a string) for an index that derives
+     * its partition (#149), refused for any other. Unreachable through the
+     * types. An unknown name is left to {@link buildIndexQuery}.
+     */
+    const invalidIndexPartition = (name, partition) => {
+        const idx = streamIndexes.find((candidate) => candidate.name === name);
+        if (idx === undefined)
+            return undefined;
+        if (idx.partition === "derived") {
+            return typeof partition === "string"
+                ? undefined
+                : `Index "${name}" derives its partition: pass the partition to read as ` +
+                    `options.partition (a string); received ${String(partition)}.`;
+        }
+        return partition === undefined
+            ? undefined
+            : `Index "${name}" is scoped to the stream; it takes no partition.`;
+    };
+    /**
+     * A query of one stream index. A stream-scoped index is queried in the
+     * stream's partition: the LSI shares the table's `pk`; a GSI's `pk`
+     * attribute carries the same value. No sort-key condition — the index holds
+     * only this stream's indexed events under that key; `Query.where` narrows
+     * the derived-key range.
+     *
+     * An index that derives its partition (#149) is queried in `partition`,
+     * which other streams (and this one's other stream ids, and snapshots) may
+     * share: the `__edd_e__` filter keeps this stream's events, and a filter on
+     * the table's `pk` — projected by every index — keeps `streamId`'s.
      *
      * @throws `[EDD-9066]` for a name the stream does not declare (unreachable
      *   through the types).
+     * @throws `[EDD-9080]` for a missing `partition` on an index that derives
+     *   it, or one passed to an index that does not (unreachable through the
+     *   types).
      */
-    const buildIndexQuery = (name, streamId) => {
+    const buildIndexQuery = (name, streamId, partition) => {
         const idx = streamIndexes.find((candidate) => candidate.name === name);
         if (idx === undefined) {
             throw new Error(`[EDD-9066] EventStream "${config.streamName}": unknown index "${String(name)}". ` +
@@ -1607,11 +1867,16 @@ export const makeStream = (config) => {
                     ? "The stream declares no indexes."
                     : `Declared: ${streamIndexes.map((candidate) => `"${candidate.name}"`).join(", ")}.`));
         }
-        return Query.make({
+        const partitionProblem = invalidIndexPartition(name, partition);
+        if (partitionProblem !== undefined) {
+            throw new Error(`[EDD-9080] EventStream "${config.streamName}": ${partitionProblem}`);
+        }
+        const streamPk = composeStreamPk(streamId);
+        const query = Query.make({
             tableName: "",
             indexName: idx.index,
             pkField: idx.pk,
-            pkValue: composeStreamPk(streamId),
+            pkValue: idx.partition === "derived" ? partition : streamPk,
             skField: idx.sk,
             entityTypes: [entityType],
             decoder: indexDecoder(idx),
@@ -1639,6 +1904,7 @@ export const makeStream = (config) => {
                 }
                 : {}),
         });
+        return idx.partition === "derived" ? Query.filterExpr(query, streamPkFilter(streamPk)) : query;
     };
     /**
      * @internal The decoder of events read through `idx`.
@@ -1685,7 +1951,11 @@ export const makeStream = (config) => {
         if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
             return yield* refuse(`limit must be a positive integer; received ${String(limit)}. Nothing was sent.`);
         }
-        let query = buildIndexQuery(name, streamId);
+        const partitionProblem = invalidIndexPartition(name, options?.partition);
+        if (partitionProblem !== undefined) {
+            return yield* refuse(`${partitionProblem} Nothing was sent.`);
+        }
+        let query = buildIndexQuery(name, streamId, options?.partition);
         if (options?.beginsWith !== undefined) {
             query = Query.where(query, { beginsWith: options.beginsWith });
         }
@@ -1702,7 +1972,7 @@ export const makeStream = (config) => {
     });
     const queryNamespace = {
         events: (streamId) => buildEventsQuery(streamId),
-        index: (name, streamId) => buildIndexQuery(name, streamId),
+        index: (name, streamId, options) => buildIndexQuery(name, streamId, options?.partition),
     };
     // ---------------------------------------------------------------------------
     // Return EventStream
@@ -1720,6 +1990,9 @@ export const makeStream = (config) => {
         },
         streamName: config.streamName,
         eventSchema: eventUnion,
+        streamIdFields: compositeFields,
+        eventMarker: entityType,
+        parseStreamId: (id) => parseStreamIdWith(config.streamName, compositeFields, id),
         snapshotConfig: snapshotSettings,
         storedAs: storage,
         indexes: indexSettings,
@@ -1775,6 +2048,9 @@ export const bind = (stream) => Effect.gen(function* () {
         },
         streamName: stream.streamName,
         eventSchema: stream.eventSchema,
+        streamIdFields: stream.streamIdFields,
+        eventMarker: stream.eventMarker,
+        parseStreamId: (id) => stream.parseStreamId(id),
         snapshotConfig: stream.snapshotConfig,
         storedAs: stream.storedAs,
         indexes: stream.indexes,
@@ -1785,7 +2061,7 @@ export const bind = (stream) => Effect.gen(function* () {
         readFrom: (streamId, afterVersion, options) => provide(stream.readFrom(streamId, afterVersion, options)),
         currentVersion: (streamId, options) => provide(stream.currentVersion(streamId, options)),
         readLatest: (streamId, options) => provide(stream.readLatest(streamId, options)),
-        readIndex: (name, streamId, options) => provide(stream.readIndex(name, streamId, options)),
+        readIndex: (name, streamId, ...options) => provide(stream.readIndex(name, streamId, ...options)),
         // The captured context carries a `Compression` registry provided where
         // the stream was bound (#147).
         measureAppend: (streamId, events, expectedVersion, options) => provide(stream.measureAppend(streamId, events, expectedVersion, options)),
@@ -1810,12 +2086,22 @@ export const bind = (stream) => Effect.gen(function* () {
  * Neither list names a key attribute: table and index keys are always
  * projected.
  */
-const projectionDefinition = (projection) => projection === "all"
+const projectionDefinition = (projection, snapshot) => projection === "all"
     ? { ProjectionType: "ALL" }
     : {
         ProjectionType: "INCLUDE",
-        NonKeyAttributes: projection === "keys" ? ["__edd_e__"] : [...EVENT_ITEM_ATTRIBUTES],
+        NonKeyAttributes: projection === "keys"
+            ? ["__edd_e__"]
+            : snapshot
+                ? [...EVENT_ITEM_ATTRIBUTES, ...SNAPSHOT_ONLY_ATTRIBUTES].sort()
+                : [...EVENT_ITEM_ATTRIBUTES],
     };
+/**
+ * @internal The snapshot item's attributes an event item does not carry: what
+ * a `"withoutMetadata"` index that holds snapshots (#149) projects besides
+ * {@link EVENT_ITEM_ATTRIBUTES}.
+ */
+const SNAPSHOT_ONLY_ATTRIBUTES = ["asOfVersion", "state"];
 /**
  * Derive the `CreateTable` fragments for the stream indexes (#140) of the given
  * streams (`EventStream` or `BoundEventStream`) — `AttributeDefinitions`,
@@ -1830,7 +2116,7 @@ const projectionDefinition = (projection) => projection === "all"
  * | `projection` | `Projection` |
  * |---|---|
  * | `"all"` (default) | `{ ProjectionType: "ALL" }` |
- * | `"withoutMetadata"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__", "data", "eventType", "streamId", "timestamp", "version"] }` |
+ * | `"withoutMetadata"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__", "data", "eventType", "streamId", "timestamp", "version"] }` — plus `"asOfVersion"` and `"state"` when a stream declaring the index puts its snapshot in it (#149) |
  * | `"keys"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__"] }` — not `KEYS_ONLY`: every read filters on `__edd_e__` |
  *
  * The deployed index must project what is declared — copy `Projection` from
@@ -1841,7 +2127,12 @@ const projectionDefinition = (projection) => projection === "all"
  * table over the limit).
  *
  * An index shared by several streams with the same definition is emitted
- * once. Lists are sorted by index name, attributes by attribute name.
+ * once — the way several streams write one GSI whose partition they derive
+ * (`partition`, #149): an order's line, payment and shipment streams under
+ * `ORDER#<orderId>`, say. Whether each declaration derives its partition or
+ * indexes its snapshot is not part of the definition: the index's key schema
+ * and projection kind are. Lists are sorted by index name, attributes by
+ * attribute name.
  *
  * - An LSI can only be created with the table, and caps the item collection
  *   of every partition key value in the table at 10 GB — entity partitions
@@ -1869,25 +2160,32 @@ const projectionDefinition = (projection) => projection === "all"
  *
  * @throws `[EDD-9067]` when two streams define the same physical index
  *   differently (another type, other key attributes, or another projection).
+ *   Whether a declaration derives its partition or indexes its snapshot is not
+ *   part of the index's definition: streams that differ only there share it.
  */
 export const indexDefinitions = (...streams) => {
+    /** Per physical index: its definition, its first declarer, and whether any declarer indexes snapshots. */
     const byIndex = new Map();
     for (const stream of streams) {
         for (const [name, raw] of Object.entries(stream.indexes)) {
-            const settings = { ...raw, projection: raw.projection ?? "all" };
+            const settings = {
+                type: raw.type,
+                index: raw.index,
+                pk: raw.pk,
+                sk: raw.sk,
+                projection: raw.projection ?? "all",
+            };
+            const snapshot = raw.snapshot === true;
             const owner = `index "${name}" of stream "${stream.streamName}"`;
             const existing = byIndex.get(settings.index);
             if (existing === undefined) {
-                byIndex.set(settings.index, {
-                    type: settings.type,
-                    index: settings.index,
-                    pk: settings.pk,
-                    sk: settings.sk,
-                    projection: settings.projection,
-                    owner,
-                });
+                byIndex.set(settings.index, { ...settings, owner, snapshot });
                 continue;
             }
+            // Several streams writing one GSI they derive the partition of (#149)
+            // is the point: one declaration indexing snapshots and another not
+            // still share it, and the projection covers the snapshots.
+            existing.snapshot ||= snapshot;
             if (existing.type !== settings.type ||
                 existing.pk !== settings.pk ||
                 existing.sk !== settings.sk ||
@@ -1910,7 +2208,7 @@ export const indexDefinitions = (...streams) => {
                 { AttributeName: settings.pk, KeyType: "HASH" },
                 { AttributeName: settings.sk, KeyType: "RANGE" },
             ],
-            Projection: projectionDefinition(settings.projection),
+            Projection: projectionDefinition(settings.projection, settings.snapshot),
         };
         attributes.add(settings.sk);
         if (settings.type === "gsi") {
@@ -2450,4 +2748,46 @@ export const foldFrom = Function.dual(3, (decider, startState, events) => {
     }
     return state;
 });
+// ---------------------------------------------------------------------------
+// Change-feed projections (#151)
+// ---------------------------------------------------------------------------
+export { batchResponse, decoder, eventFilterPattern, processBatch, projection, } from "./internal/EventProjection.js";
+/**
+ * Bind a projection to the services its operations need — `DynamoClient`,
+ * the `TableConfig`s of the stream's table and the read model's, `evolve`'s
+ * requirements, and a `Compression` registry for packed event data — so every
+ * operation has `R = never`. Like {@link bind}, it checks the registry holds
+ * the codecs the stream's `storedAs` names (`[EDD-9078]`).
+ *
+ * @example
+ * ```ts
+ * const summaries = yield* EventStore.bindProjection(OrderSummaryProjection)
+ * export const handler = (event: { Records: Array<EventStore.StreamRecord> }) =>
+ *   summaries.processBatch(event.Records, { source: "lambda" }).pipe(
+ *     Effect.map((result) => result.response),
+ *     Effect.runPromise,
+ *   )
+ * ```
+ */
+export const bindProjection = (projection) => Effect.gen(function* () {
+    const ctx = yield* Effect.context();
+    // The codec check `bind` makes, against the registry captured here.
+    yield* Effect.provide(bind(projection.stream), ctx);
+    const provide = (effect) => Effect.provide(effect, ctx);
+    return {
+        ...projection,
+        pipe() {
+            // eslint-disable-next-line prefer-rest-params
+            return Pipeable.pipeArguments(this, arguments);
+        },
+        applyBatch: (events, options) => provide(projection.applyBatch(events, options)),
+        apply: (event) => provide(projection.apply(event)),
+        catchUp: (streamId) => provide(projection.catchUp(streamId)),
+        // A multi-projection batch decodes through this, under the captured context.
+        [ProjectionDecode]: (image) => provide(projection[ProjectionDecode](image)),
+        rebuild: (streamId) => provide(projection.rebuild(streamId)),
+        // Both overloads share one implementation.
+        processBatch: ((records, options) => provide(projection.processBatch(records, options))),
+    };
+});
 //# sourceMappingURL=EventStore.js.map