create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-get.md

@@ -0,0 +1,73 @@
+---
+title: askKeyValueStoreGet
+description: Read a single record from a key-value store by its partition key.
+---
+
+# askKeyValueStoreGet
+
+Fetches one record from a [key-value store](../../../config/core/key-value-store.md) by its key, or `null` if no record with that key exists.
+
+- **Action type:** `KeyValueStoreActionType.Get`
+
+```typescript
+import { askKeyValueStoreGet } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  name: string;
+}
+
+export function* askGetUser(userId: string) {
+  const user = yield* askKeyValueStoreGet<User>('users', userId);
+  return user; // User | null
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreGet<Value>(
+  keyValueStoreName: string,
+  key: string,
+  options?: KeyValueStoreGetOptions,
+): AskResponse<Value | null>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store to read from — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
+| `key` | `string` | The partition key value of the record to fetch. |
+| `options` | `KeyValueStoreGetOptions` | Reserved for future read options; currently empty. |
+
+## Returns
+
+`Value | null` — the record if found, otherwise `null`. The `Value` type parameter is the shape of your stored record.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `KeyValueStoreGetErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
+| `KeyValueStoreGetErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an object — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askKeyValueStoreGet<User>('users', userId));
+
+if (outcome.success) {
+  const user = outcome.result; // User | null
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Related
+
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store this action reads from.
+- [askKeyValueStoreGetAll](./ask-key-value-store-get-all.md) — read every record in the store.
+- [askKeyValueStoreQuery](./ask-key-value-store-query.md) — fetch multiple records by key condition, with a sort key.
+- [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) — write the record.
+- [askKeyValueStoreDelete](./ask-key-value-store-delete.md) — remove the record.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-query-all.md

@@ -0,0 +1,58 @@
+---
+title: askKeyValueStoreQueryAll
+description: Query a key-value store and collect every matching record across all pages into one array.
+---
+
+# askKeyValueStoreQueryAll
+
+Runs [askKeyValueStoreQuery](./ask-key-value-store-query.md) repeatedly, following each page's `nextPageKey`, and returns **all** matching records as a single array. Use it when you want the whole result set and don't want to manage pagination yourself.
+
+- **Built from:** loops [askKeyValueStoreQuery](./ask-key-value-store-query.md) until there are no more pages. It is a helper story, not a distinct action.
+
+```typescript
+import { askKeyValueStoreQueryAll, kvsEqual } from 'quidproquo-core';
+
+interface Order {
+  customerId: string;
+  createdAt: number;
+}
+
+export function* askAllCustomerOrders(customerId: string) {
+  const orders = yield* askKeyValueStoreQueryAll<Order>('orders', kvsEqual('customerId', customerId));
+  return orders; // Order[]
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreQueryAll<T>(
+  keyValueStoreName: string,
+  keyCondition: KvsQueryOperation,
+  options?: Omit<KeyValueStoreQueryOptions, 'nextPageKey'>,
+): AskResponse<T[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store to query — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md). |
+| `keyCondition` | `KvsQueryOperation` | The key condition — see [Query conditions](./ask-key-value-store-query.md#query-conditions-kvsqueryoperation). |
+| `options` | `Omit<KeyValueStoreQueryOptions, 'nextPageKey'>` | The same query options as [askKeyValueStoreQuery](./ask-key-value-store-query.md#keyvaluestorequeryoptions) **except** `nextPageKey`, which the helper manages internally. `limit` here caps the size of each underlying page, not the total. |
+
+## Returns
+
+`T[]` — every record matching the key condition (and `filter`, if given), across all pages. Returns an empty array if nothing matches.
+
+## Notes
+
+- This loads the entire result set into memory. For very large result sets, prefer paging manually with [askKeyValueStoreQuery](./ask-key-value-store-query.md).
+- Errors surface the same as the underlying query (`KeyValueStoreQueryErrorTypeEnum`); catch them with `askCatch`.
+
+## Related
+
+- [askKeyValueStoreQuery](./ask-key-value-store-query.md) — the single-page action this wraps.
+- [askKeyValueStoreQuerySingle](./ask-key-value-store-query-single.md) — return just the first match.
+- [askKeyValueStoreScanAll](./ask-key-value-store-scan-all.md) — the scan equivalent (no key condition).
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-query-single.md

@@ -0,0 +1,62 @@
+---
+title: askKeyValueStoreQuerySingle
+description: Query a key-value store and return the first matching record, or null.
+---
+
+# askKeyValueStoreQuerySingle
+
+Runs [askKeyValueStoreQuery](./ask-key-value-store-query.md) and returns the **first** matching record, or `null` if there are none. Convenient for "find one" lookups — for example resolving a record by a unique attribute on a secondary index.
+
+- **Built from:** [askKeyValueStoreQuery](./ask-key-value-store-query.md), paging until at least `limit` records are collected, then returning the first. It is a helper story, not a distinct action.
+
+```typescript
+import { askKeyValueStoreQuerySingle, kvsEqual } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  email: string;
+}
+
+export function* askFindUserByEmail(email: string) {
+  const user = yield* askKeyValueStoreQuerySingle<User>('users', kvsEqual('email', email));
+  return user; // User | null
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreQuerySingle<T>(
+  keyValueStoreName: string,
+  keyCondition: KvsQueryOperation,
+  filter?: KvsQueryOperation,
+  sortAscending?: boolean,
+  limit?: number,
+): AskResponse<T | null>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `keyValueStoreName` | `string` | – | Name of the store to query — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md). |
+| `keyCondition` | `KvsQueryOperation` | – | The key condition — see [Query conditions](./ask-key-value-store-query.md#query-conditions-kvsqueryoperation). |
+| `filter` | `KvsQueryOperation` | – | Optional filter on non-key attributes, applied after the key match. |
+| `sortAscending` | `boolean` | – | Order by the sort key; `false` returns the highest/newest first. |
+| `limit` | `number` | `1` | How many records to fetch per underlying page while searching. The story still returns only the first matching record. |
+
+## Returns
+
+`T | null` — the first matching record, or `null` if nothing matches.
+
+## Notes
+
+- Because `filter` is applied after the key match, when a filter is supplied the helper pages through results until it has gathered up to `limit` records before returning the first — so a matching record isn't missed just because it fell outside the first page.
+- Errors surface the same as the underlying query (`KeyValueStoreQueryErrorTypeEnum`); catch them with `askCatch`.
+
+## Related
+
+- [askKeyValueStoreQuery](./ask-key-value-store-query.md) — the single-page action this wraps.
+- [askKeyValueStoreQueryAll](./ask-key-value-store-query-all.md) — collect every match instead of the first.
+- [askKeyValueStoreGet](./ask-key-value-store-get.md) — fetch by partition key when you already know it.
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-query.md

@@ -0,0 +1,129 @@
+---
+title: askKeyValueStoreQuery
+description: Query a page of records from a key-value store by a key condition, with optional filtering, ordering, and pagination.
+---
+
+# askKeyValueStoreQuery
+
+Reads a page of records from a [key-value store](../../../config/core/key-value-store.md) that match a **key condition** — an equality on the partition key, optionally narrowed by a range on the sort key. Returns a single page plus a cursor for the next one.
+
+- **Action type:** `KeyValueStoreActionType.Query`
+
+```typescript
+import { askKeyValueStoreQuery, kvsEqual } from 'quidproquo-core';
+
+interface Order {
+  customerId: string;
+  createdAt: number;
+  total: number;
+}
+
+export function* askRecentOrders(customerId: string) {
+  const page = yield* askKeyValueStoreQuery<Order>(
+    'orders',
+    kvsEqual('customerId', customerId),
+    { limit: 20, sortAscending: false },
+  );
+
+  return page.items; // Order[]
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreQuery<KvsItem>(
+  keyValueStoreName: string,
+  keyCondition: KvsQueryOperation,
+  options?: KeyValueStoreQueryOptions,
+): AskResponse<QpqPagedData<KvsItem>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store to query — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
+| `keyCondition` | `KvsQueryOperation` | The key condition — typically `kvsEqual('partitionKey', value)`, optionally combined (via `kvsAnd`) with a range condition on the sort key. See [Query conditions](#query-conditions-kvsqueryoperation). |
+| `options` | `KeyValueStoreQueryOptions` | Filtering, ordering, and pagination — see below. |
+
+### `KeyValueStoreQueryOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `filter` | `KvsQueryOperation` | – | An extra condition applied to non-key attributes **after** the key match. Filtered-out rows still count against `limit`. |
+| `sortAscending` | `boolean` | `true` | Order results by the sort key. `false` returns the newest/highest first. |
+| `limit` | `number` | – | Maximum number of records to return in this page. |
+| `nextPageKey` | `string` | – | Opaque cursor from a previous page's `nextPageKey`; pass it to fetch the following page. |
+| `ttlInSeconds` | `number` | – | Time-to-live in seconds for a cached result of this query. |
+
+## Query conditions (`KvsQueryOperation`)
+
+A `KvsQueryOperation` is either a single condition or a logical group. Build them with the exported helpers instead of constructing the objects by hand:
+
+```typescript
+import {
+  kvsEqual, kvsNotEqual,
+  kvsLessThan, kvsLessThanOrEqual, kvsGreaterThan, kvsGreaterThanOrEqual,
+  kvsBetween, kvsIn, kvsExists, kvsNotExists,
+  kvsBeginsWith, kvsContains, kvsNotContains,
+  kvsAnd, kvsOr,
+} from 'quidproquo-core';
+
+// key: customerId = X AND createdAt BETWEEN a and b
+const keyCondition = kvsAnd([
+  kvsEqual('customerId', 'cust-123'),
+  kvsBetween('createdAt', 1_700_000_000, 1_800_000_000),
+]);
+```
+
+Each condition helper maps to a `KvsQueryOperationType`:
+
+| Helper | `KvsQueryOperationType` | DynamoDB condition |
+| --- | --- | --- |
+| `kvsEqual(key, v)` | `Equal` | `EQ` |
+| `kvsNotEqual(key, v)` | `NotEqual` | `NE` |
+| `kvsLessThan(key, v)` | `LessThan` | `LT` |
+| `kvsLessThanOrEqual(key, v)` | `LessThanOrEqual` | `LE` |
+| `kvsGreaterThan(key, v)` | `GreaterThan` | `GT` |
+| `kvsGreaterThanOrEqual(key, v)` | `GreaterThanOrEqual` | `GE` |
+| `kvsBetween(key, a, b)` | `Between` | `BETWEEN` |
+| `kvsIn(key, values)` | `In` | `IN` |
+| `kvsExists(key)` | `Exists` | `AttributeExists` |
+| `kvsNotExists(key)` | `NotExists` | `AttributeNotExists` |
+| `kvsBeginsWith(key, v)` | `BeginsWith` | `BEGINS_WITH` |
+| `kvsContains(key, v)` | `Contains` | `CONTAINS` |
+| `kvsNotContains(key, v)` | `NotContains` | `NOT_CONTAINS` |
+
+`kvsAnd(conditions)` / `kvsOr(conditions)` combine conditions using the `KvsLogicalOperatorType` (`And` / `Or`) and can be nested. These helpers are the public builders around the internal `KvsQueryCondition` / `KvsLogicalOperator` shapes and their expression compiler — you rarely need the raw types.
+
+## Returns
+
+`QpqPagedData<KvsItem>` — one page of results:
+
+```typescript
+interface QpqPagedData<T> {
+  items: T[];
+  nextPageKey?: string; // present when more pages remain
+}
+```
+
+When `nextPageKey` is set, pass it back as `options.nextPageKey` to fetch the next page. To drain every page in one call, use [askKeyValueStoreQueryAll](./ask-key-value-store-query-all.md).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `KeyValueStoreQueryErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
+| `KeyValueStoreQueryErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+
+Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
+
+## Related
+
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store, its sort keys, and its GSIs.
+- [askKeyValueStoreQueryAll](./ask-key-value-store-query-all.md) — loop all pages into a single array.
+- [askKeyValueStoreQuerySingle](./ask-key-value-store-query-single.md) — return just the first match (or `null`).
+- [askKeyValueStoreScan](./ask-key-value-store-scan.md) — read records without a key condition.
+- [askKeyValueStoreGet](./ask-key-value-store-get.md) — fetch one record by partition key.
+- [askEventDocEventList](../../features/event-doc/ask-event-doc-event-list.md) — reads a document's event log with this query action.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-scan-all.md

@@ -0,0 +1,56 @@
+---
+title: askKeyValueStoreScanAll
+description: Scan an entire key-value store and collect every matching record across all pages into one array.
+---
+
+# askKeyValueStoreScanAll
+
+Runs [askKeyValueStoreScan](./ask-key-value-store-scan.md) repeatedly, following each page's `nextPageKey`, and returns **all** records (optionally filtered) as a single array. Like a full-table scan, this reads across every partition — use it sparingly on large stores.
+
+- **Built from:** loops [askKeyValueStoreScan](./ask-key-value-store-scan.md) until there are no more pages. It is a helper story, not a distinct action.
+
+```typescript
+import { askKeyValueStoreScanAll, kvsEqual } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  status: string;
+}
+
+export function* askAllSuspendedUsers() {
+  const users = yield* askKeyValueStoreScanAll<User>('users', kvsEqual('status', 'suspended'));
+  return users; // User[]
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreScanAll<T>(
+  storeName: string,
+  filterCondition?: KvsQueryOperation,
+): AskResponse<T[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `storeName` | `string` | Name of the store to scan — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md). |
+| `filterCondition` | `KvsQueryOperation` | Optional filter applied to every scanned record — see [Query conditions](./ask-key-value-store-query.md#query-conditions-kvsqueryoperation). Omit it to return every record. |
+
+## Returns
+
+`T[]` — every record (matching the filter, if given) across all pages. Returns an empty array if nothing matches.
+
+## Notes
+
+- This loads the entire result set into memory and reads the whole table. Prefer a keyed [askKeyValueStoreQueryAll](./ask-key-value-store-query-all.md) whenever records can be addressed by key.
+- Errors surface the same as the underlying scan (`KeyValueStoreScanErrorTypeEnum`); catch them with `askCatch`.
+
+## Related
+
+- [askKeyValueStoreScan](./ask-key-value-store-scan.md) — the single-page action this wraps.
+- [askKeyValueStoreQueryAll](./ask-key-value-store-query-all.md) — the keyed equivalent (cheaper).
+- [askKeyValueStoreGetAll](./ask-key-value-store-get-all.md) — read every record with no filter.
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-scan.md

@@ -0,0 +1,71 @@
+---
+title: askKeyValueStoreScan
+description: Scan a page of records across an entire key-value store, optionally filtered.
+---
+
+# askKeyValueStoreScan
+
+Reads a page of records from a [key-value store](../../../config/core/key-value-store.md) **without** a key condition — it walks the whole table, optionally applying a filter to every record. Unlike [askKeyValueStoreQuery](./ask-key-value-store-query.md), a scan reads across all partitions, so it is more expensive; use it only when you cannot address records by key.
+
+- **Action type:** `KeyValueStoreActionType.Scan`
+
+```typescript
+import { askKeyValueStoreScan, kvsEqual } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  status: string;
+}
+
+export function* askFirstPageOfSuspendedUsers() {
+  const page = yield* askKeyValueStoreScan<User>('users', kvsEqual('status', 'suspended'));
+  return page.items; // User[]
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreScan<KvsItem>(
+  keyValueStoreName: string,
+  filterCondition?: KvsQueryOperation,
+  nextPageKey?: string,
+): AskResponse<QpqPagedData<KvsItem>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store to scan — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
+| `filterCondition` | `KvsQueryOperation` | Optional filter applied to every scanned record. Built with the `kvs*` condition helpers — see [Query conditions](./ask-key-value-store-query.md#query-conditions-kvsqueryoperation). Omit it to return everything. |
+| `nextPageKey` | `string` | Opaque cursor from a previous page's `nextPageKey`; pass it to fetch the following page. |
+
+## Returns
+
+`QpqPagedData<KvsItem>` — one page of results:
+
+```typescript
+interface QpqPagedData<T> {
+  items: T[];
+  nextPageKey?: string; // present when more pages remain
+}
+```
+
+When `nextPageKey` is set, pass it back as the third argument to fetch the next page. To drain every page in one call, use [askKeyValueStoreScanAll](./ask-key-value-store-scan-all.md).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `KeyValueStoreScanErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
+| `KeyValueStoreScanErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+
+Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
+
+## Related
+
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store being scanned.
+- [askKeyValueStoreScanAll](./ask-key-value-store-scan-all.md) — loop all pages into a single array.
+- [askKeyValueStoreQuery](./ask-key-value-store-query.md) — the cheaper, key-addressed alternative.
+- [askKeyValueStoreGetAll](./ask-key-value-store-get-all.md) — read every record with no filter.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-update-partial-properties.md

@@ -0,0 +1,75 @@
+---
+title: askKeyValueStoreUpdatePartialProperties
+description: Patch a record from a partial object, deriving the set/remove operations automatically.
+---
+
+# askKeyValueStoreUpdatePartialProperties
+
+Updates a record in a [key-value store](../../../config/core/key-value-store.md) from a **partial object**, without hand-writing update operations. Every property in the object becomes a `Set` (or a `Remove` when the value is `undefined`); the key properties are read to address the record and are not themselves written. A more ergonomic front-end to [askKeyValueStoreUpdate](./ask-key-value-store-update.md).
+
+- **Built from:** derives a `KvsUpdate` (via `kvsSet` / `kvsRemove`) from the object and calls [askKeyValueStoreUpdate](./ask-key-value-store-update.md). It is a helper story, not a distinct action.
+
+```typescript
+import { askKeyValueStoreUpdatePartialProperties } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  name: string;
+  nickname?: string;
+}
+
+export function* askRenameUser(userId: string, name: string) {
+  // Only userId (the key) + the changed fields need to be provided.
+  const updated = yield* askKeyValueStoreUpdatePartialProperties<User, 'userId'>(
+    'users',
+    'userId',
+    { userId, name },
+  );
+
+  return updated; // User
+}
+```
+
+## Signature
+
+```typescript
+// Partition key only
+function* askKeyValueStoreUpdatePartialProperties<TModel, PartitionKey extends keyof TModel>(
+  keyValueStoreName: string,
+  partitionKeyName: PartitionKey,
+  partialProperties: Partial<TModel> & { [k in PartitionKey]: TModel[PartitionKey] },
+): AskResponse<TModel>;
+
+// Partition + sort key
+function* askKeyValueStoreUpdatePartialProperties<TModel, PartitionKey extends keyof TModel, SortKey extends keyof TModel>(
+  keyValueStoreName: string,
+  partitionKeyName: PartitionKey,
+  partialProperties: Partial<TModel> & { [k in PartitionKey]: TModel[PartitionKey] } & { [k in SortKey]: TModel[SortKey] },
+  sortKeyName: SortKey,
+): AskResponse<TModel>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md). |
+| `partitionKeyName` | `keyof TModel` | The property name that holds the partition key. That property must be present in `partialProperties`; it is used to address the record, not written. |
+| `partialProperties` | `Partial<TModel>` (with the key properties required) | The record patch. Each non-key property becomes a `Set`; a property explicitly set to `undefined` becomes a `Remove`. |
+| `sortKeyName` | `keyof TModel` | (Overload) The property name holding the sort key, when the store has one. Must be present in `partialProperties`. |
+
+## Returns
+
+`TModel` — the record after the patch is applied (the return of the underlying update).
+
+## Notes
+
+- The partition-key (and sort-key) properties are skipped when building the operations — they identify the record rather than mutate it.
+- A property whose value is `undefined` is turned into a `Remove`; a property with a valid value is turned into a `Set`. Values that aren't a supported store data type are silently skipped (validated internally via `isValidKvsAdvancedDataType`).
+- Errors surface the same as the underlying update (`KeyValueStoreUpdateErrorTypeEnum`); catch them with `askCatch`.
+
+## Related
+
+- [askKeyValueStoreUpdate](./ask-key-value-store-update.md) — the lower-level action this wraps; use it for increments, nested paths, and set operations.
+- [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) — replace the whole record instead of patching it.
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store and its keys.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-update.md

@@ -0,0 +1,106 @@
+---
+title: askKeyValueStoreUpdate
+description: Apply a set of atomic update operations to an existing record in a key-value store.
+---
+
+# askKeyValueStoreUpdate
+
+Applies a list of **update operations** (set, remove, increment, …) to a single record in a [key-value store](../../../config/core/key-value-store.md), addressed by its key. Unlike [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md), which replaces the whole item, this mutates individual attributes in place and returns the updated record.
+
+- **Action type:** `KeyValueStoreActionType.Update`
+
+```typescript
+import { askKeyValueStoreUpdate, kvsUpdate, kvsSet, kvsIncrement } from 'quidproquo-core';
+
+interface Account {
+  accountId: string;
+  balance: number;
+  lastActivity: number;
+}
+
+export function* askApplyCharge(accountId: string, amount: number, now: number) {
+  const updated = yield* askKeyValueStoreUpdate<Account>(
+    'accounts',
+    kvsUpdate([
+      kvsIncrement('balance', -amount),
+      kvsSet('lastActivity', now),
+    ]),
+    accountId,
+  );
+
+  return updated; // Account
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreUpdate<Value>(
+  keyValueStoreName: string,
+  updates: KvsUpdate,
+  key: KvsCoreDataType,
+  sortKey?: KvsCoreDataType,
+  options?: KeyValueStoreUpdateOptions,
+): AskResponse<Value>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
+| `updates` | `KvsUpdate` | The list of update operations to apply. See [Update operations](#update-operations-kvsupdate). |
+| `key` | `KvsCoreDataType` | Partition key value of the record to update (`string \| number`). |
+| `sortKey` | `KvsCoreDataType` | Sort key value, required only if the store declares a sort key (`string \| number`). |
+| `options` | `KeyValueStoreUpdateOptions` | Reserved for future update options; currently empty. |
+
+## Update operations (`KvsUpdate`)
+
+`KvsUpdate` is an array of `KvsUpdateAction`. Build each action with an exported helper rather than writing the object literal, and wrap the list with `kvsUpdate(...)` (an identity helper that keeps the call readable):
+
+```typescript
+import {
+  kvsUpdate,
+  kvsSet, kvsRemove, kvsAdd, kvsDelete,
+  kvsSetIfNotExists, kvsIncrement, kvsDecrement,
+} from 'quidproquo-core';
+
+const updates = kvsUpdate([
+  kvsSet('name', 'Ada'),
+  kvsRemove('temporaryFlag'),
+  kvsSetIfNotExists('firstSeen', now),
+  kvsIncrement('loginCount', 1),
+]);
+```
+
+| Helper | `KvsUpdateActionType` | Effect |
+| --- | --- | --- |
+| `kvsSet(path, value)` | `Set` | Create the attribute or overwrite its value. |
+| `kvsRemove(path)` | `Remove` | Delete the attribute from the item. |
+| `kvsAdd(path, value)` | `Add` | Increment a number or add elements to a set. |
+| `kvsDelete(path, value)` | `Delete` | Remove elements from a set or list attribute. |
+| `kvsSetIfNotExists(path, value)` | `SetIfNotExists` | Set the attribute only if it does not already exist (`if_not_exists`). |
+| `kvsIncrement(path, by, default?)` | `Increment` | Atomically add `by` to a numeric attribute, initializing it to `default` (0) if absent. |
+| `kvsDecrement(path, by, default?)` | `Increment` | As `kvsIncrement` but subtracts `by`. |
+
+Each `path` is a `KvsAttributePath` — either a top-level attribute name (`'balance'`) or an array of names/indexes to reach a nested attribute (`['settings', 'theme']`, `['tags', 0]`).
+
+## Returns
+
+`Value` — the record after the updates have been applied.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `KeyValueStoreUpdateErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
+| `KeyValueStoreUpdateErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+
+Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
+
+## Related
+
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store and its keys.
+- [askKeyValueStoreUpdatePartialProperties](./ask-key-value-store-update-partial-properties.md) — build the update operations automatically from a partial object.
+- [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) — write/replace a whole record instead of patching attributes.
+- [askKeyValueStoreGet](./ask-key-value-store-get.md) — read the record.