effect-dynamodb 1.26.0 → 1.28.0

package/dist/EventStore.d.ts

@@ -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).
@@ -32,6 +39,7 @@ import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
 import { AdditionalItemConditionFailed, AppendTooLarge, type ConcurrentModification, DuplicateCommand, type OptimisticLockError, TransactionCancelled, type UniqueConstraintViolation, ValidationError, VersionConflict } from "@effect-dynamodb/schema/Errors.js";
 import { DateTime, type Duration, Effect, Option, Pipeable, Schedule, Schema } from "effect";
 import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
+import { type EventProjection } from "./internal/EventProjection.js";
 import { type StreamImage } from "./internal/Packed.js";
 import { type TransactWriteOp } from "./internal/TransactWriteOps.js";
 import * as Query from "./Query.js";
@@ -397,6 +405,14 @@ export type AppendError = VersionConflict | DuplicateCommand | AdditionalItemCon
 export interface ReadOptions {
     readonly consistentRead?: boolean | undefined;
 }
+/**
+ * Options accepted by {@link EventStream.readFrom}: {@link ReadOptions} plus
+ * `toVersion`, the last version to read (inclusive) — the key condition stops
+ * there, so nothing past it is read or paid for. Default: the stream's head.
+ */
+export interface ReadFromOptions extends ReadOptions {
+    readonly toVersion?: number | undefined;
+}
 /**
  * Options accepted by {@link EventStream.readLatest}: {@link ReadOptions} plus
  * `verifySnapshot`.
@@ -444,20 +460,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 +490,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 +560,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 +578,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 +639,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 +648,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 +681,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 +713,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 +732,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 +751,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 +766,47 @@ export type ReadIndexOptions = {
     readonly between?: readonly [string, string] | undefined;
     readonly beginsWith?: undefined;
 });
-type StreamIdInput<T extends ReadonlyArray<string>> = {
+/**
+ * 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];
+export 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,15 +820,32 @@ 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;
+    /** The stream id's composite fields, in declaration order (`makeStream({ streamId })`). */
+    readonly streamIdFields: TStreamIdFields;
+    /**
+     * The `__edd_e__` value of the stream's event items (`<streamname>.event`,
+     * lower-cased) — what a change-feed filter or {@link decoder} matches on.
+     */
+    readonly eventMarker: string;
+    /**
+     * Recover the structured stream id from a {@link StreamEvent.streamId} —
+     * the composites joined with `#`, in declaration order. A single-field id is
+     * the whole string. A multi-field id is split on `#`; a part count other
+     * than the field count (a value that itself contains `#`) is ambiguous and
+     * fails with `ValidationError`.
+     */
+    parseStreamId(streamId: string): Effect.Effect<StreamIdInput<TStreamIdFields>, ValidationError, never>;
     /**
      * The stream's indexes (`makeStream({ indexes })`) by name — their physical
      * index and key attributes. Empty for a stream without indexes.
@@ -719,10 +905,11 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      */
     read(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
     /**
-     * Read the events after `afterVersion` (exclusive), ascending. Pass
-     * `{ consistentRead: true }` for read-your-writes — see {@link ReadOptions}.
+     * Read the events after `afterVersion` (exclusive), ascending — up to
+     * `toVersion` (inclusive) when given. Pass `{ consistentRead: true }` for
+     * read-your-writes — see {@link ReadFromOptions}.
      */
-    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number, options?: ReadFromOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
     /**
      * The version of the stream's newest event (`0` for an empty stream), in one
      * request. Pass `{ consistentRead: true }` for read-your-writes — see
@@ -769,8 +956,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 +1038,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 +1103,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 +1128,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 +1182,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 +1211,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 +1219,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,10 +1247,16 @@ 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;
+    /** See {@link EventStream.streamIdFields}. */
+    readonly streamIdFields: TStreamIdFields;
+    /** See {@link EventStream.eventMarker}. */
+    readonly eventMarker: string;
+    /** See {@link EventStream.parseStreamId}. */
+    parseStreamId(streamId: string): Effect.Effect<StreamIdInput<TStreamIdFields>, ValidationError, never>;
     /** See {@link EventStream.snapshotConfig}. */
     readonly snapshotConfig: SnapshotSettings | undefined;
     /** See {@link EventStream.storedAs}. */
@@ -1030,13 +1274,13 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
     /** See {@link EventStream.read}. */
     read(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.readFrom}. */
-    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
+    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number, options?: ReadFromOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.currentVersion}. */
     currentVersion(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<number, DynamoClientError | ValidationError, never>;
     /** 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 +1300,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 +1319,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 +1345,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 +1356,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 +1389,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 +1762,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 +1862,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.
@@ -1633,4 +1888,23 @@ export declare const foldFrom: {
     <A>(startState: unknown, events: ReadonlyArray<StreamEvent<A>>): <S, C, E>(decider: Decider<S, C, A, E>) => S;
     <S, C, A, E>(decider: Decider<S, C, A, E>, startState: S, events: ReadonlyArray<StreamEvent<A>>): S;
 };
+export { type AnyEventProjection, type ApplyBatchOptions, type BatchItemFailuresResponse, type BatchResponseSource, batchResponse, type CheckpointField, type DecodableStream, type DecodedStreamEvent, decoder, type EventFilterPattern, type EventProjection, type EventProjectionTypeId, eventFilterPattern, type IdentifyBySource, type IdentifyWith, type ProcessBatchesResult, type ProcessBatchOptions, type ProcessBatchResult, type ProjectionApplied, type ProjectionBatchResult, type ProjectionCaughtUp, type ProjectionCheckpoint, type ProjectionConfig, type ProjectionError, type ProjectionKey, type ProjectionOutcome, type ProjectionOutcomesOf, type ProjectionReadModel, type ProjectionReadModelError, type ProjectionRebuilt, type ProjectionRebuiltRow, type ProjectionRejected, type ProjectionRequirementsOf, type ProjectionState, processBatch, projection, type StreamRecord, } 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 declare const bindProjection: <S, A, TStreamIdFields extends ReadonlyArray<string>, M, Err, R, K, E, I extends boolean>(projection: EventProjection<S, A, TStreamIdFields, M, Err, R, K, E, I>) => Effect.Effect<EventProjection<S, A, TStreamIdFields, M, Err, never, K, E, I>, never, R>;
 //# sourceMappingURL=EventStore.d.ts.map