effect-dynamodb 1.26.0 → 1.27.0

package/dist/EventStore.d.ts

@@ -15,7 +15,9 @@
  * - 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 —
@@ -444,20 +446,27 @@ export interface LatestState<TState, TEvent, M = Record<string, unknown> | undef
     readonly events: ReadonlyArray<StreamEvent<TEvent, M>>;
     readonly version: number;
 }
+/**
+ * The stream id as a stream's index functions receive it: the value of each
+ * `streamId.composite` field, by name.
+ */
+export type StreamIndexStreamId = {
+    readonly [field: string]: string;
+};
 /**
  * Derives an event's key in a stream index from the domain event (before it is
- * encoded) and the version it is appended at.
+ * encoded), the version it is appended at — its version in the stream — and
+ * the stream id it is appended to.
  *
  * - A string is the event's sort key in the index. It is stored **raw**: no
  *   casing and no prefixing is applied, so compose it to sort the way you
  *   query (zero-pad numbers, for example).
  * - `undefined` leaves the event out of the index (a sparse index).
- * - An empty string (or any other value) fails the append with
- *   `ValidationError` before anything is written — DynamoDB rejects empty key
- *   values — as does a `key` that throws. A key over DynamoDB's 1024-byte
- *   sort-key limit is sent and rejected by DynamoDB; the append then fails
- *   with `ValidationError` naming the index and the event (#144), and nothing
- *   is written.
+ * - Any other value, or a `key` that throws, fails the append with
+ *   `ValidationError` before anything is written. An empty string or a key
+ *   over DynamoDB's 1024-byte sort-key limit is sent and rejected by
+ *   DynamoDB; the append then fails with `ValidationError` naming the index
+ *   and the event (#144), and nothing is written.
  *
  * The key is derived only when an event is appended. Events are never
  * rewritten, so changing `key` later leaves events already stored under their
@@ -467,7 +476,60 @@ export interface LatestState<TState, TEvent, M = Record<string, unknown> | undef
  * existing events is the application's decision (see `indexes` on
  * {@link makeStream}).
  */
-export type StreamIndexKey<TEvent> = (event: TEvent, version: number) => string | undefined;
+export type StreamIndexKey<TEvent, TStreamId = StreamIndexStreamId> = (event: TEvent, version: number, streamId: TStreamId) => string | undefined;
+/**
+ * Derives an event's partition in a GSI stream index (`partition` on a
+ * {@link GlobalStreamIndexConfig}, #149) from the domain event, the version it
+ * is appended at and the stream id — the arguments of the index's `key`, in
+ * the same order. Called for every appended event, with `key`.
+ *
+ * - A string is the event's partition key in the index, stored **raw** (no
+ *   casing, no prefix) in the index's `pk` attribute. Several streams may
+ *   derive the same value, so one query of the index reads a group of
+ *   streams — `ORDER#<orderId>` for an order's line, payment and shipment
+ *   streams, say.
+ * - `undefined` leaves the event out of the index, as an `undefined` `key`
+ *   does. An event is indexed only when both return a string.
+ * - Within one append, every event whose partition is a string must have the
+ *   same one, and so must the inline snapshot's entry (see
+ *   {@link StreamIndexSnapshotEntry}); otherwise the append fails with
+ *   `ValidationError` and nothing is written. Another value, or a function
+ *   that throws, fails it the same way. An empty string, or one over
+ *   DynamoDB's 2048-byte partition-key limit, is DynamoDB's to reject: the
+ *   rejection is reported as a `ValidationError` naming the index and the
+ *   event.
+ */
+export type StreamIndexPartition<TEvent, TStreamId = StreamIndexStreamId> = (event: TEvent, version: number, streamId: TStreamId) => string | undefined;
+/**
+ * Puts a stream's snapshot in a GSI stream index with a derived partition
+ * (`snapshot` on a {@link GlobalStreamIndexConfig}, #149): from the state
+ * being written (before it is encoded), the snapshot's `asOfVersion` and the
+ * stream id — in the order of the events' `key` and `partition` — the
+ * snapshot item's partition and sort key in the index —
+ * both stored **raw** — or `undefined` to leave it out.
+ *
+ * Every snapshot write derives it — `writeSnapshot`, the inline snapshot of
+ * `append` and `commandHandler` (`mode: "inline"` or `"after-append"`) — and
+ * the attributes are part of the snapshot item itself, so an inline snapshot
+ * enters the index in the append's own transaction. The snapshot `Put`
+ * replaces the whole item, so returning `undefined` takes a snapshot already
+ * in the index out of it.
+ *
+ * The inline snapshot of an append must have the partition of the append's
+ * events in the index (when they have one); a standalone `writeSnapshot` has
+ * no events to compare with. Another value than an object of two strings, or
+ * a function that throws, fails the write with `ValidationError` before
+ * anything is written.
+ *
+ * A snapshot is the state **as of** `asOfVersion`: it is current after every
+ * append only with `snapshot: { mode: "inline" }` and no `every`. A reader of
+ * the index that needs the head folds the stream's indexed events after
+ * `asOfVersion` onto it.
+ */
+export type StreamIndexSnapshotEntry<TState, TStreamId = StreamIndexStreamId> = (state: TState, asOfVersion: number, streamId: TStreamId) => {
+    readonly partition: string;
+    readonly key: string;
+} | undefined;
 /**
  * A stream index on a **local** secondary index (the default `type`). An LSI
  * shares the table's partition key (`pk`), so its items are exactly the
@@ -484,13 +546,17 @@ export type StreamIndexKey<TEvent> = (event: TEvent, version: number) => string
  * the index copies from each event is its `projection` — see
  * {@link StreamIndexProjection}.
  */
-export interface LocalStreamIndexConfig<TEvent> {
+export interface LocalStreamIndexConfig<TEvent, TStreamId = StreamIndexStreamId> {
     readonly type?: "lsi" | undefined;
     readonly index: string;
     readonly sk: string;
     /** An LSI uses the table partition key; supplying `pk` is refused (`[EDD-9063]`). */
     readonly pk?: undefined;
-    readonly key: StreamIndexKey<TEvent>;
+    readonly key: StreamIndexKey<TEvent, TStreamId>;
+    /** An LSI's partition is the stream's; supplying `partition` is refused (`[EDD-9063]`). */
+    readonly partition?: undefined;
+    /** Only a GSI with a derived `partition` indexes snapshots (`[EDD-9063]`). */
+    readonly snapshot?: undefined;
     /**
      * What the index copies from each event — see {@link StreamIndexProjection}.
      * Default `"all"`. Must match the deployed index.
@@ -498,30 +564,56 @@ export interface LocalStreamIndexConfig<TEvent> {
     readonly projection?: StreamIndexProjection | undefined;
 }
 /**
- * A stream index on a **global** secondary index. `append` writes the stream's
- * partition key value into the `pk` attribute of each indexed event, so the
- * index is scoped to the same stream: the eventually consistent equivalent of
- * an LSI, without the LSI's 10 GB item-collection cap. DynamoDB rejects a
- * strongly consistent read of it, diagnosed as a `ValidationError` naming the
- * index.
+ * A stream index on a **global** secondary index. By default `append` writes
+ * the stream's partition key value into the `pk` attribute of each indexed
+ * event, so the index is scoped to the same stream: the eventually consistent
+ * equivalent of an LSI, without the LSI's 10 GB item-collection cap. DynamoDB
+ * rejects a strongly consistent read of it, diagnosed as a `ValidationError`
+ * naming the index.
+ *
+ * With `partition` (#149), the partition is derived instead — see
+ * {@link StreamIndexPartition} — and stored raw, so several streams can write
+ * the same partition of one GSI they all declare, and one query of it reads
+ * the whole group (an order's line, payment and shipment streams under
+ * `ORDER#<orderId>`, say). {@link indexDefinitions} emits a physical index
+ * the streams declare alike once. With `snapshot` as well, each stream's
+ * snapshot item is in the index too — see {@link StreamIndexSnapshotEntry}.
+ * {@link EventStream.readIndex} then takes the partition to read, and
+ * returns the given stream's events in it.
  *
  * Unlike an LSI, the GSI itself can be added to an existing table
- * (`UpdateTable`), but that does not index the stream's existing events: the
- * index attributes are written only by `append`, so only events appended after
- * the index is declared are in it — see {@link StreamIndexKey}.
+ * (`UpdateTable`), but that does not index the stream's existing items: the
+ * index attributes are written only by `append` (and snapshot writes), so only
+ * events appended after the index is declared are in it — see
+ * {@link StreamIndexKey}.
  *
  * - `index` — the physical GSI name.
- * - `pk` — the attribute carrying the stream's partition key (the GSI's HASH key).
+ * - `pk` — the attribute carrying the partition (the GSI's HASH key): the
+ *   stream's partition key, or the derived `partition`.
  * - `sk` — the attribute carrying the derived key (the GSI's RANGE key).
  * - `key` — see {@link StreamIndexKey}.
+ * - `partition` — optional, see {@link StreamIndexPartition}.
+ * - `snapshot` — optional, requires `partition` and a stream `snapshot`
+ *   config; see {@link StreamIndexSnapshotEntry}.
  * - `projection` — see {@link StreamIndexProjection}.
+ *
+ * Write `type: "gsi"` in the entry itself. TypeScript infers the parameter
+ * types of `partition` and `snapshot` from the GSI member of the entry union,
+ * which it selects by the literal `type`: an entry whose `type` comes from an
+ * object spread (`{ ...shared, partition: (event) => … }`) gets implicit-`any`
+ * parameters there, although `key` still infers. Annotate them, or give the
+ * shared fragment a {@link GlobalStreamIndexConfig} type.
  */
-export interface GlobalStreamIndexConfig<TEvent> {
+export interface GlobalStreamIndexConfig<TEvent, TStreamId = StreamIndexStreamId, TState = unknown> {
     readonly type: "gsi";
     readonly index: string;
     readonly pk: string;
     readonly sk: string;
-    readonly key: StreamIndexKey<TEvent>;
+    readonly key: StreamIndexKey<TEvent, TStreamId>;
+    /** The derived partition — see {@link StreamIndexPartition}. */
+    readonly partition?: StreamIndexPartition<TEvent, TStreamId> | undefined;
+    /** The snapshot's entry — see {@link StreamIndexSnapshotEntry}. Requires `partition`. */
+    readonly snapshot?: StreamIndexSnapshotEntry<TState, TStreamId> | undefined;
     /**
      * What the index copies from each event — see {@link StreamIndexProjection}.
      * Default `"all"`. Must match the deployed index.
@@ -533,7 +625,7 @@ export interface GlobalStreamIndexConfig<TEvent> {
  * ordered by a key derived from each event. See {@link LocalStreamIndexConfig}
  * and {@link GlobalStreamIndexConfig}.
  */
-export type StreamIndexConfig<TEvent> = LocalStreamIndexConfig<TEvent> | GlobalStreamIndexConfig<TEvent>;
+export type StreamIndexConfig<TEvent, TStreamId = StreamIndexStreamId, TState = unknown> = LocalStreamIndexConfig<TEvent, TStreamId> | GlobalStreamIndexConfig<TEvent, TStreamId, TState>;
 /**
  * What a stream index copies from each event (`projection` on an entry of
  * `makeStream({ indexes })`). {@link indexDefinitions} emits the matching
@@ -542,7 +634,7 @@ export type StreamIndexConfig<TEvent> = LocalStreamIndexConfig<TEvent> | GlobalS
  * | Value | Emitted `Projection` | Read |
  * |---|---|---|
  * | `"all"` (default) | `ALL` | one query |
- * | `"withoutMetadata"` | `INCLUDE` of every event attribute except `metadata` | one query; `metadata` is `undefined` (and typed so) |
+ * | `"withoutMetadata"` | `INCLUDE` of every event attribute except `metadata` (plus the snapshot's `asOfVersion` and `state` when a stream indexes its snapshot in it) | one query; `metadata` is `undefined` (and typed so) |
  * | `"keys"` | `INCLUDE ["__edd_e__"]` — **not** `KEYS_ONLY` | LSI: one query with `Select: ALL_ATTRIBUTES` (DynamoDB fetches each event from the table). GSI: the query, then `BatchGetItem` for the events of each page, in index order |
  *
  * `__edd_e__` is always projected because every read filters on it, and
@@ -575,6 +667,18 @@ export interface StreamIndexSettings {
     readonly pk: string;
     readonly sk: string;
     readonly projection: StreamIndexProjection;
+    /**
+     * Where the index's partition comes from: `"stream"` — the stream's own
+     * partition key (every LSI, and a GSI without `partition`) — or
+     * `"derived"`, a GSI's `partition` function (#149). A stream always sets
+     * it; absent (a settings object built by hand) reads as `"stream"`.
+     */
+    readonly partition?: "stream" | "derived" | undefined;
+    /**
+     * Whether the stream's snapshot is in the index (a GSI's `snapshot`, #149).
+     * A stream always sets it; absent reads as `false`.
+     */
+    readonly snapshot?: boolean | undefined;
 }
 /**
  * The `metadata` type of an event read through a stream index of projection
@@ -595,6 +699,16 @@ type ProjectionOf<C> = C extends {
 export type IndexProjectionsOf<TIndexes> = {
     readonly [K in keyof TIndexes & string]: ProjectionOf<TIndexes[K]>;
 };
+/**
+ * The names of the indexes of a `makeStream({ indexes })` config that derive
+ * their partition (`partition`, #149) — those {@link EventStream.readIndex}
+ * and `query.index` read with an explicit `partition`.
+ */
+export type PartitionedIndexesOf<TIndexes> = {
+    readonly [K in keyof TIndexes & string]: TIndexes[K] extends {
+        readonly partition: (...args: ReadonlyArray<any>) => unknown;
+    } ? K : never;
+}[keyof TIndexes & string];
 /** @internal The members a stream index entry may declare. */
 type StreamIndexConfigKey = keyof LocalStreamIndexConfig<unknown> | keyof GlobalStreamIndexConfig<unknown>;
 /**
@@ -604,8 +718,8 @@ type StreamIndexConfigKey = keyof LocalStreamIndexConfig<unknown> | keyof Global
  * `TIndexes` from the entries turns off TypeScript's own excess-property check,
  * which would otherwise catch it.
  */
-export type StreamIndexesConfig<TIndexes, TEvent> = {
-    readonly [K in keyof TIndexes]: StreamIndexConfig<TEvent> & {
+export type StreamIndexesConfig<TIndexes, TEvent, TStreamId = StreamIndexStreamId, TState = unknown> = {
+    readonly [K in keyof TIndexes]: StreamIndexConfig<TEvent, TStreamId, TState> & {
         readonly [P in Exclude<keyof TIndexes[K], StreamIndexConfigKey>]: never;
     };
 };
@@ -623,6 +737,9 @@ export type StreamIndexesConfig<TIndexes, TEvent> = {
  * - `consistentRead` — strongly consistent read. DynamoDB rejects it on a
  *   GSI-backed index, which it reads only eventually consistently: the read
  *   fails with a `ValidationError` naming the index.
+ *
+ * An index that derives its partition (#149) also takes `partition` — see
+ * {@link ReadIndexArgs}.
  */
 export type ReadIndexOptions = {
     readonly reverse?: boolean | undefined;
@@ -635,9 +752,47 @@ export type ReadIndexOptions = {
     readonly between?: readonly [string, string] | undefined;
     readonly beginsWith?: undefined;
 });
+/**
+ * The options argument of {@link EventStream.readIndex} for index `N`. An
+ * index that derives its partition (`partition`, #149) is read one partition
+ * at a time, so `partition` — the value to read, as the index's `partition`
+ * function returns it — is required, and the read returns the events of the
+ * given stream in it. Any other index is scoped to the stream already: a
+ * `partition` passed for it fails the read with `ValidationError` (it stays
+ * in the type so that a stream whose indexes derive their partition remains
+ * assignable to one whose indexes do not, as every stream is to
+ * `EventStream<E, F, M, S>`).
+ */
+export type ReadIndexArgs<N extends string, TPartitionedIndexName extends string> = [
+    TPartitionedIndexName
+] extends [never] ? [
+    options?: (ReadIndexOptions & {
+        readonly partition?: string | undefined;
+    }) | undefined
+] : [N] extends [TPartitionedIndexName] ? [options: ReadIndexOptions & {
+    readonly partition: string;
+}] : [options?: (ReadIndexOptions & {
+    readonly partition?: string | undefined;
+}) | undefined];
+/**
+ * The options argument of `query.index` for index `N` — `partition`, required
+ * for an index that derives its partition, as for {@link ReadIndexArgs}; on
+ * any other index, one passed throws `[EDD-9080]`.
+ */
+export type IndexQueryArgs<N extends string, TPartitionedIndexName extends string> = [
+    TPartitionedIndexName
+] extends [never] ? [options?: {
+    readonly partition?: string | undefined;
+} | undefined] : [N] extends [TPartitionedIndexName] ? [options: {
+    readonly partition: string;
+}] : [options?: {
+    readonly partition?: string | undefined;
+} | undefined];
 type StreamIdInput<T extends ReadonlyArray<string>> = {
     readonly [K in T[number]]: string;
 };
+/** @internal The state type of a `makeStream({ snapshot })` config; `never` without one. */
+type SnapshotStateOf<TSnapshot> = TSnapshot extends SnapshotConfig<infer TStateSchema> ? Schema.Schema.Type<TStateSchema> : never;
 declare const EventStreamTypeId: unique symbol;
 export type EventStreamTypeId = typeof EventStreamTypeId;
 /**
@@ -651,12 +806,14 @@ export type EventStreamTypeId = typeof EventStreamTypeId;
  * `query.index` only accept a declared name. `TIndexProjections` is each
  * index's {@link StreamIndexProjection} by name, so an event read through a
  * `"withoutMetadata"` index has `metadata: undefined`.
+ * `TPartitionedIndexName` names the indexes that derive their partition
+ * (#149), which are read with an explicit `partition`.
  */
 export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState = never, TIndexName extends string = never, TIndexProjections extends {
     readonly [K in TIndexName]: StreamIndexProjection;
 } = {
     readonly [K in TIndexName]: "all";
-}> extends Pipeable.Pipeable {
+}, TPartitionedIndexName extends string = never> extends Pipeable.Pipeable {
     readonly [EventStreamTypeId]: EventStreamTypeId;
     readonly streamName: string;
     readonly eventSchema: Schema.Top;
@@ -769,8 +926,14 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * `metadata: undefined`, as the type says); for `"keys"`, one query with
      * `Select: ALL_ATTRIBUTES` on an LSI, or the query followed by `BatchGetItem`
      * (unprocessed keys retried, index order kept) on a GSI.
+     *
+     * An index that derives its partition (`partition`, #149) is read one
+     * partition at a time: pass the partition as `options.partition` (required
+     * by the types — see {@link ReadIndexArgs}). The read keeps the events of
+     * `streamId` in it — not the other streams sharing the partition, nor any
+     * snapshot — by filtering on the table's `pk`, which every index projects.
      */
-    readIndex<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    readIndex<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, ...options: ReadIndexArgs<N, TPartitionedIndexName>): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
     /**
      * The bytes {@link EventStream.append} would write for these arguments, by
      * DynamoDB's own size accounting — for planning chunks against the 400 KB
@@ -845,8 +1008,12 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
          * counts index entries and fetches nothing. On a `"keys"` or
          * `"withoutMetadata"` index, a `Query.filter` on an attribute the index
          * does not project is refused by DynamoDB — use `Query.filterBy`.
+         *
+         * An index that derives its partition (#149) takes the partition to read
+         * as `options.partition` (see {@link IndexQueryArgs}), and the query keeps
+         * `streamId`'s events in it, as {@link EventStream.readIndex} does.
          */
-        index<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
+        index<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, ...options: IndexQueryArgs<N, TPartitionedIndexName>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
     };
 }
 /**
@@ -906,11 +1073,20 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  * `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
@@ -922,6 +1098,36 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  *
  * @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",
@@ -946,10 +1152,12 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  * @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
@@ -973,7 +1181,7 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  */
 export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top>, TTable extends Table, const TStreamName extends string, const TStreamId extends {
     readonly composite: ReadonlyArray<string>;
-}, TMetadata extends Schema.Top | undefined = undefined, TSnapshot extends SnapshotConfig | undefined = undefined, const TIndexes extends { readonly [K in keyof TIndexes]: StreamIndexConfig<Schema.Schema.Type<TEvents[number]>>; } = {}>(config: {
+}, TMetadata extends Schema.Top | undefined = undefined, TSnapshot extends SnapshotConfig | undefined = undefined, const TIndexes extends { readonly [K in keyof TIndexes]: StreamIndexConfig<Schema.Schema.Type<TEvents[number]>, StreamIdInput<TStreamId["composite"]>, SnapshotStateOf<TSnapshot>>; } = {}>(config: {
     readonly table: TTable;
     readonly streamName: TStreamName;
     readonly events: TEvents;
@@ -981,10 +1189,10 @@ export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top
     readonly metadata?: TMetadata;
     readonly snapshot?: TSnapshot;
     readonly casing?: DynamoSchema.Casing | undefined;
-    readonly indexes?: TIndexes & StreamIndexesConfig<TIndexes, Schema.Schema.Type<TEvents[number]>>;
+    readonly indexes?: TIndexes & StreamIndexesConfig<TIndexes, Schema.Schema.Type<TEvents[number]>, StreamIdInput<TStreamId["composite"]>, SnapshotStateOf<TSnapshot>>;
     /** How event `data` is stored — see {@link StreamStorageConfig}. */
     readonly storedAs?: StreamStorageConfig | undefined;
-}) => EventStream<Schema.Schema.Type<TEvents[number]>, TStreamId["composite"], TMetadata extends Schema.Top ? Schema.Schema.Type<TMetadata> : undefined, TSnapshot extends SnapshotConfig<infer TStateSchema> ? Schema.Schema.Type<TStateSchema> : never, keyof TIndexes & string, IndexProjectionsOf<TIndexes>>;
+}) => EventStream<Schema.Schema.Type<TEvents[number]>, TStreamId["composite"], TMetadata extends Schema.Top ? Schema.Schema.Type<TMetadata> : undefined, SnapshotStateOf<TSnapshot>, keyof TIndexes & string, IndexProjectionsOf<TIndexes>, PartitionedIndexesOf<TIndexes>>;
 /**
  * An EventStream whose operations have `DynamoClient` and `TableConfig` already
  * resolved, so all methods return `Effect<A, E, never>`.
@@ -1009,7 +1217,7 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
     readonly [K in TIndexName]: StreamIndexProjection;
 } = {
     readonly [K in TIndexName]: "all";
-}> extends Pipeable.Pipeable {
+}, TPartitionedIndexName extends string = never> extends Pipeable.Pipeable {
     readonly [EventStreamTypeId]: EventStreamTypeId;
     readonly streamName: string;
     readonly eventSchema: Schema.Top;
@@ -1036,7 +1244,7 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
     /** See {@link EventStream.readLatest}. */
     readLatest(streamId: StreamIdInput<TStreamIdFields>, options?: ReadLatestOptions | undefined): Effect.Effect<LatestState<TState, TEvent, StreamMetadata<TMetadata>>, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.readIndex}. */
-    readIndex<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, DynamoClientError | ValidationError, never>;
+    readIndex<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, ...options: ReadIndexArgs<N, TPartitionedIndexName>): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.measureAppend}. */
     measureAppend(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: MeasureAppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendMeasurement, ValidationError, never>;
     /** See {@link EventStream.measureSnapshot}. */
@@ -1056,7 +1264,7 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
     readonly query: {
         events(streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, StreamMetadata<TMetadata>>>;
         /** See `EventStream.query.index`. */
-        index<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
+        index<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, ...options: IndexQueryArgs<N, TPartitionedIndexName>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
     };
     /** Escape hatch: provide DynamoClient | TableConfig to an arbitrary effect. */
     readonly provide: <A, E>(effect: Effect.Effect<A, E, DynamoClient | TableConfig>) => Effect.Effect<A, E, never>;
@@ -1075,7 +1283,7 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
  * yield* stream.append({ matchId: "m-1" }, [event], 0)     // R = never
  * ```
  */
-export declare const bind: <TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState, TIndexName extends string = never, TIndexProjections extends { readonly [K in TIndexName]: StreamIndexProjection; } = { readonly [K in TIndexName]: "all"; }>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>, never, DynamoClient | TableConfig>;
+export declare const bind: <TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState, TIndexName extends string = never, TIndexProjections extends { readonly [K in TIndexName]: StreamIndexProjection; } = { readonly [K in TIndexName]: "all"; }, TPartitionedIndexName extends string = never>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, never, DynamoClient | TableConfig>;
 /**
  * `CreateTable` fragments for the stream indexes of one or more streams — see
  * {@link indexDefinitions}. The lists are absent when empty, because
@@ -1101,7 +1309,7 @@ export interface StreamIndexDefinitions {
  * | `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
@@ -1112,7 +1320,12 @@ export interface StreamIndexDefinitions {
  * 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
@@ -1140,13 +1353,19 @@ export interface StreamIndexDefinitions {
  *
  * @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 declare const indexDefinitions: (...streams: ReadonlyArray<{
     readonly streamName: string;
     readonly indexes: {
-        readonly [name: string]: Omit<StreamIndexSettings, "projection"> & {
+        readonly [name: string]: Omit<StreamIndexSettings, "projection" | "partition" | "snapshot"> & {
             /** Read as `"all"` when absent (a hand-built settings object). */
             readonly projection?: StreamIndexProjection | undefined;
+            /** Read as `"stream"` when absent (a hand-built settings object). */
+            readonly partition?: "stream" | "derived" | undefined;
+            /** Read as `false` when absent (a hand-built settings object). */
+            readonly snapshot?: boolean | undefined;
         };
     };
 }>) => StreamIndexDefinitions;
@@ -1507,7 +1726,7 @@ type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends Read
  * stream is also structurally an `EventStream`), a {@link CommandHandler}
  * otherwise.
  */
-type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHandlerOptions | undefined> = S extends BoundEventStream<any, infer TStreamIdFields, infer TMetadata, any, any> ? BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig> : S extends EventStream<any, infer TStreamIdFields, infer TMetadata, any, any> ? CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig> : never;
+type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHandlerOptions | undefined> = S extends BoundEventStream<any, infer TStreamIdFields, infer TMetadata, any, any, any, any> ? BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig> : S extends EventStream<any, infer TStreamIdFields, infer TMetadata, any, any, any, any> ? CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig> : never;
 /**
  * Create a command handler that reads, decides, and appends atomically.
  *
@@ -1607,13 +1826,13 @@ type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHand
  * `EventStreamTypeId` brand of the second argument.
  */
 export declare const commandHandler: {
-    <State, Command, TEvent, E, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, options?: TConfig): <S extends BoundEventStream<TEvent, any, any, State, any, any> | EventStream<TEvent, ReadonlyArray<string>, any, State, any, any>>(stream: S) => CommandHandlerFor<S, State, Command, TEvent, E, TConfig>;
+    <State, Command, TEvent, E, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, options?: TConfig): <S extends BoundEventStream<TEvent, any, any, State, any, any, any> | EventStream<TEvent, ReadonlyArray<string>, any, State, any, any, any>>(stream: S) => CommandHandlerFor<S, State, Command, TEvent, E, TConfig>;
     <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, TIndexName extends string, TIndexProjections extends {
         readonly [K in TIndexName]: StreamIndexProjection;
-    }, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>, options?: TConfig): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
+    }, TPartitionedIndexName extends string, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, options?: TConfig): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
     <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, TIndexName extends string, TIndexProjections extends {
         readonly [K in TIndexName]: StreamIndexProjection;
-    }, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
+    }, TPartitionedIndexName extends string, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
 };
 /**
  * Reconstruct state from events by folding through a decider's `evolve` function.