create-qpq-app 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -52,7 +52,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.13"
+    "quidproquo-tsconfig": "0.1.14"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

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

@@ -55,6 +55,7 @@ function* askKeyValueStoreQuery<KvsItem>(
 | `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. |
+| `consistentRead` | `boolean` | `false` | Strongly consistent (read-your-own-writes) read. Costs roughly double the read capacity on DynamoDB and cannot be served from a global secondary index. Use it when a caller just wrote and is now querying to decide something (e.g. folding a log right after appending to it); leave it off for ordinary reads. |
 | `ttlInSeconds` | `number` | – | Accepted but not implemented: no processor currently applies a TTL to query results, so setting it has no effect. |
 | `scope` | `string` | – | Optional storage scope. The processor composes it into the partition-key conditions, so the query only matches records written under the same scope (used by tenant/scoped features). Requires a string-typed partition key, and the key condition must constrain the partition key. |
 

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-event-list.md

@@ -46,6 +46,7 @@ function* askEventDocEventList(
 | `limit` | `number` | (store default) | Max number of events to return in the page. |
 | `nextPageKey` | `string` | — | Continuation token from a previous page's `nextPageKey`. |
 | `afterEventId` | `string` | — | Return only events whose event id sorts after this one (exclusive). A sort-key range condition on the events store's primary key — no GSI involved. |
+| `consistentRead` | `boolean` | `false` | Strongly consistent read. Needed by a caller that just appended and is now folding to decide something — the default eventually-consistent read can otherwise miss that caller's own most recent event. Costs roughly double the read capacity, so leave it off for ordinary reads. |
 
 ### Returns
 
@@ -66,7 +67,10 @@ export function* fullHistory(docId: string) {
 ### Signature
 
 ```typescript
-function* askEventDocEventListAll(modelId: string): AskResponse<EventDocEvent[]>;
+function* askEventDocEventListAll(
+  modelId: string,
+  options?: { consistentRead?: boolean },
+): AskResponse<EventDocEvent[]>;
 ```
 
 ### Parameters
@@ -74,6 +78,7 @@ function* askEventDocEventListAll(modelId: string): AskResponse<EventDocEvent[]>
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `modelId` | `string` | The document id to read the full log for. |
+| `options.consistentRead` | `boolean` | Optional, default `false`. Strongly consistent read — for a caller that just appended and is now folding to decide something, so it does not miss its own most recent event. Leave off for ordinary reads; it doubles the read cost. |
 
 ### Returns
 

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-generate-asset-upload-url.md

@@ -1,13 +1,13 @@
 ---
 title: askEventDocGenerateAssetUploadUrl
-description: Manage a document's immutable assets — mint presigned upload/download URLs, or write server-generated bytes directly.
+description: Manage a document's immutable assets and size-aware values — mint presigned upload/download URLs, write server-generated bytes directly, or record a value inline vs as an asset depending on its size.
 ---
 
 # Document assets
 
 A document can point at binary **assets** — images, fonts, rendered artifacts — without embedding the bytes. Each asset is stored immutably on the collection's storage drive under `<docId>/assets/<guid>`, and the document records only a reference (the guid) inside a domain event. Because every upload gets a fresh guid, a re-upload is a new blob and prior references stay addressable for history and rollback.
 
-These three helpers cover the two flows: presigned URLs for a browser to upload/download bytes directly, and a server-side write for when the backend already holds the bytes.
+These helpers cover three flows: presigned URLs for a browser to upload/download bytes directly, a server-side write for when the backend already holds the bytes, and a size-aware write that decides between inline and asset storage for values of unpredictable size.
 
 - **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals). The drive name is resolved from that context.
 - **Built from:** the core file secure-URL / binary-write actions on the collection's storage drive, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore). Not single actions.
@@ -115,10 +115,49 @@ function* askEventDocWriteAsset(
 
 `AskResponse<EventDocAssetRef>` — `{ guid, filename, mimetype }`, a first-class reference to record in a domain event so the document points at the bytes without embedding them.
 
+## askEventDocWriteValue
+
+Records a **value** (data of unpredictable size — a node output, a variable, a trigger input) for an event: inline when it is small enough, or as an asset when it is not. This is the size-aware counterpart to `askEventDocWriteAsset` above, which stays the right choice for genuine files where a reference is always correct.
+
+```typescript
+import { askEventDocWriteValue } from 'quidproquo-features';
+
+export function* recordNodeOutput(docId: string, nodeId: string, output: unknown) {
+  const ref = yield* askEventDocWriteValue(docId, output, `${nodeId}.json`);
+  // ref is either { kind: 'inline', value } or { kind: 'asset', guid, filename, mimetype }
+  return ref;
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocWriteValue(
+  docId: string,
+  value: unknown,
+  filename: string,
+  maxInlineBytes?: number,
+): AskResponse<EventDocValueRef>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the value belongs to — used for the asset blob key when the value doesn't fit inline. |
+| `value` | `unknown` | The value to record. Serialised with `JSON.stringify`; `undefined` is normalised to `null`. |
+| `filename` | `string` | Filename to use if the value is written as an asset. |
+| `maxInlineBytes` | `number` | Optional, default 4KB. The per-value inline ceiling. A caller recording several values against one event's combined size budget can pass the *remaining* budget so a value that no longer fits falls back to an asset; passing `0` always forces an asset. |
+
+### Returns
+
+`AskResponse<EventDocValueRef>` — either `{ kind: 'inline', value }` (the value travelled in the event, nothing to fetch) or `{ kind: 'asset', guid, filename, mimetype }` (fetch it like any other asset reference).
+
 ## Notes
 
-- All three resolve the drive from the store context, so a missing context throws (see [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore)).
+- All four resolve the drive from the store context, so a missing context throws (see [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore)).
 - Assets are immutable: guid-named so a re-upload is always a fresh blob; the old one stays addressable for history/rollback. Assets live under `<docId>/assets/<guid>`; derived, disposable artifacts use a sibling `<docId>/runtime/<...>` prefix written elsewhere.
+- On the read side, `isInlineEventDocValueRef`, `readInlineEventDocValueRefs`, and `resolveEventDocValueRef` (all in `quidproquo-features`) are the shared helpers for branching on a ref's `kind` and resolving it against fetched asset snapshots — use them rather than checking `ref.kind` by hand, so every reader agrees on what "available" means.
 
 ## Related
 

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-list.md

@@ -1,13 +1,17 @@
 ---
 title: askEventDocList
-description: List every event document in the current collection, newest-updated first, hiding soft-deleted rows by default.
+description: List event documents in the current collection, newest-updated first, hiding soft-deleted rows by default — as a full array or one page at a time.
 ---
 
-# askEventDocList
+# Listing a collection
 
-Lists the summary records of every document in the current collection (all rows sharing the collection's `type`), sorted by `updatedAt` **descending** (most recently updated first). Soft-deleted documents are hidden unless you opt in.
+Two ways to list the summary records of a collection (all rows sharing the collection's `type`), sorted by `updatedAt` **descending** (most recently updated first). Soft-deleted documents are hidden unless you opt in. Both require the store context — call inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
 
-- **Built from:** a key-value store query over the collection's `type`, filtered and sorted in memory. Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
+## askEventDocList
+
+Reads the **whole** collection into memory, filters and sorts it, and returns it as a flat array. Fine for a handful of documents; costs read capacity proportional to the whole collection, so it does not scale to a large collection — use [askEventDocListPage](#askeventdoclistpage) for that.
+
+- **Built from:** a key-value store query over the collection's `type`, filtered and sorted in memory.
 
 ```typescript
 import { askEventDocList } from 'quidproquo-features';
@@ -18,7 +22,7 @@ export function* listArticles() {
 }
 ```
 
-## Signature
+### Signature
 
 ```typescript
 function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
@@ -26,9 +30,9 @@ function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
 ): AskResponse<T[]>;
 ```
 
-## Parameters
+### Parameters
 
-### `options` — `EventDocListOptions` (optional)
+#### `options` — `EventDocListOptions` (optional)
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -36,18 +40,60 @@ function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
 
 The generic `T` lets callers narrow to a collection-specific extension of [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record); it defaults to `EventDocSummary`.
 
-## Returns
+### Returns
 
 `EventDocSummary[]` — the collection's records, sorted by `updatedAt` descending. Empty array when the collection has no (visible) documents.
 
-## Notes
+### Notes
 
 - Ordering is applied in memory, but the summary store carries a `(type, updatedAt)` index so this stays efficient.
 - Because there is no secondary index on `code`, the code-based reads ([askEventDocGetByCode](./ask-event-doc-get-by-code.md) and friends) list the collection via this action and filter in memory.
 
+## askEventDocListPage
+
+Reads **one page** of the collection straight off the store, newest first, without reading or holding the rest of the collection in memory. This is what the built-in `GET {basePath}` list route uses.
+
+- **Built from:** [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) against the summary store, ordered by its `(type, updatedAt)` index (descending), with soft-deleted rows excluded by a query filter.
+
+```typescript
+import { askEventDocListPage } from 'quidproquo-features';
+
+export function* listArticlesPage(nextPageKey?: string) {
+  return yield* askEventDocListPage({ nextPageKey }); // QpqPagedData<EventDocSummary>
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocListPage<T extends EventDocSummary = EventDocSummary>(
+  options?: EventDocListPageOptions,
+): AskResponse<QpqPagedData<T>>;
+```
+
+### Parameters
+
+#### `options` — `EventDocListPageOptions` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `includeDeleted` | `boolean` | `false` | When `true`, soft-deleted documents are included. When `false` (default), they are excluded by a query filter. |
+| `limit` | `number` | `10` | 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. |
+
+### Returns
+
+`AskResponse<QpqPagedData<T>>` — `{ items: T[]; nextPageKey?: string }`, one page ordered by `updatedAt` descending.
+
+### Notes
+
+- Because the exclusion of soft-deleted rows is a query filter (applied **after** rows are read), a page can come back shorter than `limit` while more pages remain. Page on the presence of `nextPageKey`, never on item count, or documents past a short page are silently hidden.
+- There is no jump-to-page-N or total count without reading the whole collection — the store hands back an opaque "continue from here" cursor, not an offset, so pages are walked rather than addressed.
+
 ## Related
 
 - [askEventDocGetById / askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md) — read a single document.
 - [askEventDocGetByCode](./ask-event-doc-get-by-code.md) — find one document by its business `code`.
-- [askEventDocSoftDelete](./ask-event-doc-soft-delete.md) — sets the `deletedAt` this action filters on.
-- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store (and its ordering index) this reads from.
+- [askEventDocSoftDelete](./ask-event-doc-soft-delete.md) — sets the `deletedAt` these actions filter on.
+- [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) — the underlying paged query action.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store (and its ordering index) these read from.

package/template/docusaurus/docs/config/core/queue.md

@@ -52,7 +52,7 @@ Each key is matched against a delivered message's `type` field. The key may be a
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `batchSize` | `number` | `0` | Max number of messages delivered to the consumer Lambda per invocation. `0` leaves the SQS default. When set (> 0), the event source uses this batch size. |
-| `batchWindowInSeconds` | `number` | `5` | Max time SQS waits to fill a batch before invoking the consumer. Only applied when `batchSize > 0`, and **not** applied to FIFO queues (which don't support a batching window). |
+| `batchWindowInSeconds` | `number` | `0` | Max time SQS waits to fill a batch before invoking the consumer — invoke as soon as a message arrives. Only applied when `batchSize > 0`, and **not** applied to FIFO queues (which don't support a batching window). A queue that wants to accumulate a batch before invoking should set this explicitly. |
 | `concurrency` | `number` | `1` | Consumer concurrency hint. |
 | `maxTries` | `number` | `1` | How many times a message is delivered before it is sent to the dead-letter queue (SQS `maxReceiveCount`). |
 | `ttRetryInSeconds` | `number` | `900` | Retry/visibility timeout in seconds — how long a message stays invisible while being processed before it can be redelivered. Also used as the consumer Lambda timeout. Capped at 900 (15 minutes). |

package/template/docusaurus/docs/config/features/event-doc-routes.md

@@ -31,7 +31,7 @@ All paths are prefixed with the version segment `/v{version}` (default `/v1`):
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `{basePath}` | List the collection's documents. |
+| `GET` | `{basePath}` | List one page of the collection's documents (newest first). Accepts `?limit=` and `?nextPageKey=` and returns `QpqPagedData`. |
 | `GET` | `{basePath}/{id}` | Get one document's summary record. |
 | `GET` | `{basePath}/{id}/events` | List a document's event log. |
 | `GET` | `{basePath}/{id}/render` | Render the document to HTML. **Only mounted when `eventRenderer` is set.** |