@owlmeans/resource 0.1.18-rc.2 → 0.1.18-rc.21

package/agent-meta/skills/resource/SKILL.md

@@ -8,20 +8,28 @@ user-invocable: false
 # @owlmeans/resource
 
 **Layer:** Core
-**Install:** `"@owlmeans/resource": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/resource": "^0.1.18-rc.21"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`save`/`create`/`update`/`delete`/`pick`. |
-| `MigratableResource<Tx>` | **Optional migration capability** — `migration(name, apply, stage?)` (chainable) + `migrations()`. Optional the way pub/sub is on redis resources: mongo and postgres extend it, backends with nothing to migrate don't. |
+| `ResourceRecord` | `{ id?: string }` — the constraint every record type satisfies, and the only field the contract itself knows about. |
+| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`count`/`create`/`update`/`save`/`delete`/`take`/`purge`. Reads take **an id or a criteria object**; `list(where?, opts?)` takes `{ page, size, sort }` flat in the second argument. |
+| `Criteria<T>`, `FieldCriteria<V>`, `FieldOperators<V>` | The query language, typed by the record — a mistyped field is a compile error. |
+| `Sort<T>`, `SortField<T>`, `FirstOptions<T>`, `ListOptions<T>`, `ListQuery<T>`, `ListResult<T>` | Ordering, the read options, the one-object form an API carries over the wire, and the answer shape `{ items, total, page?, size? }`. |
+| `WriteOptions`, `Ttl` | `{ ttl }` on `create`/`update`/`save`; seconds from now, or the instant to expire at. Backends without expiry refuse it. |
+| `matchCriteria`, `filterRecords`, `sortRecords`, `firstMatch`, `applyQuery` | The shared in-memory engine — one criteria object means the same thing in a browser store as it does in SQL. |
+| `PubSubResource<T>`, `WatchableResource<T>`, `StreamResource<T>`, `LockableResource<T>` | **Optional capabilities**, composed into a concrete resource interface alongside `Resource<T>`. `SubscribeOptions` (`{ channel, once, ttl }`) and `Unsubscribe` come with the first two. |
+| `MigratableResource<Tx, Self>` | **Optional migration capability** — `migration(name, apply, stage?)` (chainable) + `migrations()`. Optional the way pub/sub is on redis resources: mongo and postgres extend it, backends with nothing to migrate don't. |
 | `Migration`, `MigrationRegistry`, `MigrationStore`, `MigrationReport`, `MigrationRunOptions` | The framework's contracts. `MigrationStore` is the *migration register* a database implements to track applied migrations (`ensure`/`applied`/`baseline`/`run`). |
 | `createMigrationRegistry<Tx>()` | Storage-agnostic ledger of code-registered migrations per alias. Declaration order = application order; re-registering an identical body is a no-op, a changed body under a used name throws `MigrationConflict`. |
 | `runMigrations(alias, registry, store, opts?)` | Apply one stage's pending migrations through a store. `baseline: true` records instead of running (fresh structures); `strictChecksum` (default on) rejects edited applied bodies. |
 | `MigrationStage` | `Pre` (before structure reconciliation — renames, casts, rescues) / `Post` (after — backfills into new structure). |
-| `createDbService` | Base for `ResourceDbService` implementations (config/alias/name/client plumbing). |
-| `prepareListOptions`, `filterObject`, `createListSchema` | List/criteria helpers. |
+| `createDbService` | Base for `ResourceDbService` implementations (config/alias/name/client plumbing). The service's `name(alias?)` resolves to `config.schema ?? config.alias ?? service.alias`. |
+| `ResourceDbService<Db, Client>`, `DbLocker<T>` | What a connection service implements: `db`/`client`/`clients`/`config`/`name`/`ensureConfigAlias`/`initialize`, plus `lock`/`unlock` when the backend encrypts fields. |
+| `ResourceMaker<R, T>` | `(dbAlias?, serviceAlias?) => T` — the signature every resource maker is typed with, so an app registers `makeXResource()` without repeating the argument list. |
+| `filterObject(obj, keep?)`, `createListSchema` | Drop null and undefined properties, keeping the names listed in `keep`; the AJV schema for a `ListResult<T>` envelope. |
 | Errors | `ResourceError`, `UnknownRecordError`, `MisshapedRecord`, `RecordExists`, `RecordUpdateFailed`, `UnsupportedArgumentError`, `UnsupportedMethodError`, `MigrationError`, `MigrationConflict`. |
 | `DbConfig`, `Config`, `Context` | Database config (`cfg.dbs`) types. |
 
@@ -35,11 +43,128 @@ A resource is a typed CRUD-over-records abstraction. Concrete implementations co
 ```typescript
 import type { Resource } from '@owlmeans/resource'
 
-interface Project { id: string; name: string; entityId: string }
+interface Project { id: string; name: string; entityId: string; createdAt: Date }
 const projects = ctx.resource<Resource<Project>>('projects')
-const { items } = await projects.list({ entityId: 'abc' })
+
+// A read is addressed by an id OR by criteria — fetching one record by several fields is a
+// single call, never a list whose first element is taken.
+const project = await projects.get('abc123')
+const newest = await projects.load({ entityId: 'abc' }, { sort: [{ field: 'createdAt', order: 'desc' }] })
+
+// Paging and sort are FLAT in the second argument.
+const page2 = await projects.list({ entityId: 'abc' }, { page: 1, size: 20, sort: ['createdAt'] })
+page2.items      // the window
+page2.total      // every record the criteria match, not just this page
+```
+
+### Calling the CRUD surface
+
+A **write** takes the record as its only data argument, and the id travels inside it. There is no
+`(id, changes)` overload on any of them — passing an id first fails to compile with
+`TS2559: Type 'string' has no properties in common with type 'Partial<...>'`.
+
+| Call | Signature | Notes |
+|---|---|---|
+| `create(record, opts?)` | `Partial<T> → T` | throws `RecordExists`; implementations may refuse a caller-supplied id |
+| `save(record, opts?)` | `Partial<T> → T` | creates when the record carries no id, replaces otherwise |
+| `update(record, opts?)` | `Partial<T> → T` | replaces the whole record; throws `UnknownRecordError` |
+
+A **read** is addressed either by an id or by a criteria object. The id overload takes nothing
+else; the criteria overload takes `{ sort }` to say which match is "the" one:
+
+| Call | Signature | Notes |
+|---|---|---|
+| `load(id)` / `load(where, { sort })` | `→ T \| null` | the miss-tolerant read |
+| `get(id)` / `get(where, { sort })` | `→ T` | throws `UnknownRecordError` instead of returning `null` |
+| `list(where?, { page, size, sort })` | `→ { items, total, page?, size? }` | `total` counts every match, not the window |
+| `count(where?)` | `→ number` | the same question without carrying the records back |
+| `delete(id)` | `→ T \| null` | returns what it removed |
+| `take(id)` | `→ T` | **deletes the record it returns.** It is a `delete` that throws `UnknownRecordError` on a miss, never a read — never reach for it to fetch something |
+| `purge(where)` | `→ number` | bulk delete; refuses an empty criteria object rather than emptying the resource |
+
+Every method returns the record(s) themselves, never a driver result object — there is no
+`rowsAffected`/`rowCount` anywhere on this contract.
+
+### The criteria language
+
+`Criteria<T>` is keyed by the record's own fields, so a typo is a compile error. A dotted key
+reaches into a nested value (or a jsonb column) and stays open.
+
+| Written as | Means |
+|---|---|
+| `{ status: 'open' }` | equality |
+| `{ status: ['open', 'done'] }` | **any of these** — a bare array is never exact-array equality (that is `{ $eq: [...] }`) |
+| `{ archivedAt: null }` | the absence of a value |
+| `{ status: undefined }` | **skipped** — an untouched filter must never empty a list |
+| `{ 'profile.city': 'Kraków' }` | reach into a nested value or a jsonb column |
+
+Operators go in an object under the field: `$eq $ne $gt $gte $lt $lte $in $nin $exists $null
+$like $ilike $regex $startsWith $endsWith $between $contains $contained $overlaps`. Branches
+combine with `$and` / `$or` / `$not`, each taking criteria of the same shape.
+
+```typescript
+await projects.list({
+  entityId: 'abc',
+  createdAt: { $gte: since },
+  $or: [{ name: { $ilike: 'owl%' } }, { tags: { $overlaps: ['pinned'] } }]
+})
 ```
 
+Every backend answers the same object the same way — that is the point of the vocabulary. An
+operator a store cannot express raises `UnsupportedArgumentError` rather than being quietly
+dropped.
+
+`Sort<T>` is a bare field name (ascending) or `{ field, order: 'asc' | 'desc' }`, and `sort` takes
+a list of them. Where an **absent** value lands is the store's own rule, not the vocabulary's: the
+in-memory sorter puts it last ascending, Postgres emits a bare `ASC` and so leaves it last (the
+server's `NULLS LAST` default), and Mongo hands the sort document to the driver untouched, so BSON
+ordering puts null and missing first. Sort on a field the schema requires when the position of an
+absent value matters.
+
+### Paging is a property of the backend
+
+`ListResult<T>` is `{ items, total, page?, size? }` — `total` always counts every match. Whether a
+missing `size` means "everything" depends on what the store can afford:
+
+| Backend | `list(where)` with no `size` |
+|---|---|
+| mongo, postgres | a page of `DEFAULT_PAGE_SIZE` (100) — an unbounded read of a growing table is an incident waiting to happen |
+| redis, static, client-resource, config, state | every match — answering the criteria already read the whole namespace, so an implied window would only hide records without saving work |
+
+`size: 0` means **no limit** on every backend — the explicit, greppable way to ask for a whole
+result set. `page` without `size` against an unpaged backend throws
+`UnsupportedArgumentError('page-without-size')`: there is no implied default to take a window of.
+
+### The shared in-memory engine
+
+Every store without a query engine of its own — redis after its SCAN, the client and static
+stores, state — filters through the same helpers, so a criteria object written for an endpoint
+selects the same records when a screen applies it locally:
+
+| Helper | Answers |
+|---|---|
+| `matchCriteria(record, where)` | does this one record match |
+| `filterRecords(records, where)` | every match, in insertion order |
+| `sortRecords(records, sort)` | a sorted copy |
+| `firstMatch(records, where, { sort })` | the record `load(where)` / `get(where)` return |
+| `applyQuery(records, where, opts)` | the whole `ListResult` — filter, sort and page in one call |
+
+Reach for them when implementing a backend, and when narrowing a list already in hand rather than
+going back to the store.
+
+### Optional capabilities
+
+A concrete resource interface composes the capabilities its backend actually has beside
+`Resource<T>`; a consumer types the **resource** once and gets exactly those methods.
+
+| Interface | Surface |
+|---|---|
+| `PubSubResource<T>` | `publish(value, channel?)` · `subscribe(handler, { channel?, once?, ttl? })` |
+| `WatchableResource<T>` | `watch(id, handler, { once?, ttl? })` — changes to ONE record |
+| `StreamResource<T>` | `stream(key, value)` · `consume(key, { group?, consumer?, block? })` |
+| `LockableResource<T>` | `lock`/`unlock` — field level encryption at rest |
+| `MigratableResource<Tx, Self>` | `migration(name, apply, stage?)` · `migrations()` |
+
 ## The migration framework
 
 Migrations are **automatic on app setup**: a backend runs them inside the resource's
@@ -51,9 +176,11 @@ Adding migration support to a new database backend:
 
 1. Extend the concrete resource interface with `MigratableResource<YourTx>` and design the
    `Tx` façade a migration receives.
-2. Keep registrations in a **module-scope declaration keyed by alias** (see either
-   implementation's `declarations.ts`) — `reinitializeContext` rebuilds resource objects, and
-   a registry lost to a rebuild silently loses data transformations.
+2. Keep registrations in a **module-scope declaration keyed by alias** — the shape mongo and
+   postgres both expose as `getDeclaration(alias)` / `resetDeclarations(alias?)`. A maker that
+   runs more than once for the same alias (a custom maker, a test) then re-declares the same
+   entries and loses nothing, where a registry held on the resource object would silently lose
+   data transformations.
 3. Implement `MigrationStore` over a durable ledger when the database can store one
    (`_owlmeans_migrations` in both mongo and postgres); a store-less backend may run
    migrations unconditionally if its bodies are self-checking.
@@ -66,7 +193,12 @@ Adding migration support to a new database backend:
 ## Depends On
 
 - `@owlmeans/context` — service/resource lifecycle
-- `@noble/hashes` — migration body checksums
+- `@owlmeans/error` — `ResilientError`, the base every error class above extends
+- peer `ajv` — `createListSchema` builds a `JSONSchemaType`; install it when you use that schema
+
+The migration framework checksums bodies with `@noble/hashes` and `@scure/base`, and the package
+declares neither. Install both alongside it in any project that loads `createMigrationRegistry` or
+`runMigrations`, or the import fails at load time.
 
 ## Related
 

package/agent-meta/skills/resource-choice/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: resource-choice
+description: Which storage or execution mechanism a feature should use — postgres-resource, mongo-resource, redis-resource, static-resource, state, client-resource, config, storage-resource, queue + worker, or llm/agent. Guidance by similarity to worked cases, with an explicitly skeptical test for asynchronous processing. Use at design time, before writing a resource registration, a schema, or a job declaration.
+user-invocable: true
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Choosing a resource
+
+Every OwlMeans feature that keeps or moves data picks from the same short list. The list is short
+on purpose: one `Resource` contract ([[resource]]) covers all of them, so the choice is about
+where the bytes live and when the work runs — not about a new API to learn.
+
+This is guidance by **similarity**, not an algorithm. Find the case under "Worked cases" below
+that most resembles what you are building and take its answer; the rules in between say why those
+answers came out that way, and how far you can carry one to a case that is not listed. When two
+options look equally right, pick the one already registered in the app.
+
+## The default
+
+**Postgres.** `@owlmeans/postgres-resource` is the answer for records the product owns and the
+product queries: users, orders, projects, comments, settings, audit rows. It gets the default
+because it is the only backend here that gives all of relational integrity, real query planning,
+transactions, and DDL derived from the resource's AJV schema — and because being wrong with it is
+cheap. Nothing else on this page is a place to *start*; each one is a place to move to for a named
+reason.
+
+Say "start with Postgres, move only if measured" out loud whenever the argument for something else
+is a guess about load. A resource that turns out to be hot moves later, and the criteria objects,
+paging and sorting come with it unchanged — that portability is what makes deferring the decision
+safe.
+
+## The options
+
+| Option | It is for | It is not for |
+|---|---|---|
+| `postgres-resource` | Records with structure, relations, and queries — the default | Anything the schema cannot describe up front |
+| `mongo-resource` | Documents whose shape varies per record or per tenant; deep nesting read whole | Rows you will join, sum, or report across |
+| `redis-resource` | Data with an expiry, a lock, a counter, or a fan-out — and a **small, namespaced** key set | A source of truth, or an unbounded keyspace (`list`/`count` walk it) |
+| `static-resource` | In-process records with no database behind them — fixtures, handshake state, a per-process cache | Anything that must survive a restart or be seen by a second replica |
+| `state` | Client-side records a screen binds to, reached through the context | Anything that must outlive the tab |
+| `client-resource` | Client-side records that must survive a reload, over a key-value store (`web-db` gives the browser one) | A query surface — the whole store is walked per read |
+| `config` | Reading the records the process was configured with, as a resource | Anything written at runtime — every write is refused |
+| `storage-resource` | The **bytes** of a file, in an S3-compatible bucket (upload only) | The record describing the file — that stays in postgres or mongo |
+| `queue` + a worker process | Work that must outlive the request, be retried, or be spread over workers | Anything the request can finish itself (see below) |
+| `llm` / `agent` | Work whose output is judgement or language, not a computation | A rule you can write down |
+
+### Postgres or Mongo
+
+Ask what a *reader* does with the record. Filter, sort, join, aggregate, report — Postgres, and
+the AJV schema becomes the table ([[postgres-resource]]). Load whole by id, with a shape that
+differs per record and a nesting depth no column list wants to model — Mongo, and the AJV schema
+becomes the validator ([[mongo-resource]]). Both carry migrations, indexes, locks and the same
+criteria language, so this is a modelling decision, not a capability one.
+
+A single varying corner inside an otherwise relational record is not a reason to move the whole
+resource: Postgres maps a nested `object` — and an `array` whose items are not plain scalars — to
+`jsonb`, where a criteria *object* written against the column becomes containment (`@>`). An
+`array` of plain `string`/`integer`/`number`/`boolean` items is a different case: it becomes a
+native array column, queried with `$contains` / `$contained` / `$overlaps`.
+
+### Redis and the four things it is actually good at
+
+`redis-resource` earns its place when the data has one of these properties, not when it is merely
+"fast":
+
+- **Expiry** — the record is meant to disappear: sessions, OTPs, nonces, magic-link tokens, an
+  idempotency key's memory. TTL is a per-call option on `create`/`update`/`save`, and `update`
+  rewrites the key, so a renewal must pass the TTL again or the record becomes permanent.
+- **Cache** — a derived value it would be embarrassing to recompute per request. A cache is
+  correct only if a miss is invisible to the user; if losing it changes behaviour, it is state, and
+  state belongs in the database.
+- **Lock** — one worker at a time, with an expiry so a dead holder does not block forever. Postgres
+  and Mongo resources also expose `lock`/`unlock`; use theirs when the lock guards *their* rows.
+- **Counter / rate limit / fan-out** — increments, windows, and pub/sub between processes.
+
+The hard limit: reads by id are single-key commands, but `load(where)`, `list`, `count` and `purge`
+**walk the resource's namespace** with `SCAN` and evaluate criteria in memory, unpaged and not
+cluster-safe. A resource that needs real queries belongs in Mongo or Postgres, however hot it is.
+
+### static-resource, state and client-resource
+
+`static-resource` is a `Map` at module scope wearing the `Resource` contract. It is right for
+fixtures, a getting-started app with no database, and short-lived handshake state in a
+single-process deployment — and wrong the moment there are two replicas, because each one holds a
+different truth. Do not reach for it as a cache in a scaled service; that is Redis.
+
+`state` is the same contract on the client: records a screen binds to through `useStoreModel` /
+`useStoreList`, with `watch`/`query` for the live half. Draft state, the current user, a wizard in
+progress, an optimistic list. It is a store, not a security boundary — the server re-validates
+everything that arrives from it.
+
+`client-resource` is the client store that **survives a reload**: same criteria language, backed by
+a key-value store an app registers under `cfg.dbs` (`@owlmeans/web-db` supplies the browser's
+IndexedDB one). Reach for it for an offline cache, a remembered filter set, a queued write waiting
+for connectivity — and expect the cost, because records live under their own ids with one list of
+ids as the only index, so every criteria read walks the store. `state` for what the screen is
+holding right now, `client-resource` for what has to be there tomorrow, the server for the truth.
+
+### Files
+
+Bytes go to `storage-resource` (upload only — a bucket has no index). The **record** describing
+them — url, size, mime type, owner, status — goes in a database resource, and that record is what
+answers criteria, sorting and paging. Image-shaped names and schemas for it are in
+[[image-resource]].
+
+## Be skeptical about queues
+
+Asynchronous processing is the most over-applied answer on this page. It multiplies the number of
+places a feature can fail, it needs a second process to deploy and watch, and it makes every
+processor a thing that must be safe to run twice. Do not add it because the work "feels heavy".
+
+**A request that finishes in under ~2 seconds and makes no external call never queues.** Do it
+inline and return the answer.
+
+Asynchronous work earns its complexity when at least one of these is true:
+
+1. **The user would otherwise wait more than ~5 seconds.** Not "the work takes 5 seconds" — the
+   *user waits*. Work nobody is watching can still be inline if the caller is a script.
+2. **It must survive a process restart.** A deploy, an OOM kill, or a pod eviction mid-operation
+   would otherwise lose work that was already accepted, and nothing would retry it.
+3. **It is retried against a third party.** Payment captures, provider syncs, mail sends and
+   webhook deliveries fail transiently and must be re-attempted with backoff, without the user
+   re-submitting.
+
+If none holds, the honest answer is "do it in the request". If exactly one holds, look for the
+smaller fix first: a database index, a batch write, a cached aggregate, or an HTTP call moved off
+the critical path. Reach for the broker when the work is genuinely detached from the request.
+
+When you do queue ([[queue]], driver [[redis-queue]]):
+
+- A queued call is an ordinary entrypoint call — `job()` in place of `backend()`. Nothing at the
+  call site says "queue", so this stays a declaration change.
+- Derive `JobOptions.id` from what the job is ABOUT (`develop:<storyId>`) and a duplicate enqueue
+  is a no-op. That is what makes an admission step safe to retry.
+- `reply: false` is fire-and-forget; the default waits for the value. Choose deliberately.
+- Every processor must be safe to run twice, and `touch()` in every long loop — the broker judges
+  liveness by the lock, and silence past `lockDuration` re-runs the job somewhere else.
+- Retries default to one attempt, which is right for expensive work and wrong for cheap idempotent
+  work — set `attempts` per queue.
+- Work that fans out into steps is one `flow(root)` graph, not a processor that enqueues its own
+  successors: children complete before the parent runs and it reads their results through
+  `children()`. Give the children of a cross-queue flow distinct ids.
+
+**There is no scheduler in the framework.** `JobOptions.delay` defers one job once; anything
+recurring — a nightly digest, an hourly reconciliation — is triggered from outside the process by
+a platform cron (a Kubernetes `CronJob` in a [[kluster]] deployment) that calls a normal entrypoint
+or enqueues a job. Do not simulate cron with a self-re-enqueueing job.
+
+## Model-driven work
+
+Reach for [[llm]] when the output is language or judgement — summaries, classification with fuzzy
+boundaries, extraction from prose, moderation, translation — and for [[agent]] when the work needs
+several turns, tools, or memory across a conversation. Everything a rule can express should stay a
+rule: a regex, a criteria object, or an AJV schema is cheaper, deterministic, and testable.
+
+Model calls are slow and paid for per attempt, so they interact with the previous section:
+
+- A single `ask` behind a user's click is fine inline when it streams; the user sees progress.
+- A pipeline of calls, or work over many records, is queue work — it is exactly case 1 and 3 above.
+- A blind retry re-spends the tokens that just failed. That is why queue retries default to one.
+- Store the *result* in a normal resource. A model output nobody persisted will be paid for again.
+
+## Choosing more than one
+
+Most real features use two. A file upload is `storage-resource` for the bytes plus a Postgres row
+for the record. A rate limiter is Redis for the window plus Postgres for the policy. An import is
+a Postgres staging table plus a queue for the work plus Redis for the progress the UI polls. Split
+by property — durability, expiry, size, latency — and let each part sit where that property is
+cheap.
+
+## Worked cases
+
+Find the row that most resembles what you are building. The answer is a starting point with a
+reason attached, not a verdict — if your case differs in a way the rules above care about, the
+answer changes with it. `postgres` / `mongo` / `redis` / `static` / `client` / `storage` below mean
+the matching `@owlmeans/*-resource` package, `state` and `config` the packages of those names, and
+`queue` means `@owlmeans/queue` plus a worker process.
+
+### Records and reads
+
+| Case | Choice | Why |
+|---|---|---|
+| Audit log | postgres | Append-only rows that are filtered, sorted and paged by whoever reads them; retention is a scheduled delete, not a TTL. |
+| Domain records (orders, projects, tickets) | postgres | The default: structure, relations, transactions, one AJV schema that becomes the table. |
+| Per-tenant custom forms / submissions | mongo | The shape differs per tenant, so no column list fits; each submission is read whole by id. |
+| Generated-app content documents | mongo | Deeply nested, revised whole, never aggregated across. |
+| Settings / feature flags per organization entity | postgres | Few rows, read constantly, always by `entityId` — cache in Redis only after measuring, and only if a stale read is harmless. |
+| Search over the product's own records | postgres | Start with indexed columns and `jsonb` containment; move to a search engine when a measured query, not a guess, says so. |
+| Expensive aggregate on a dashboard | postgres, then redis | Compute it in SQL first. Cache in Redis with a TTL only once the measured query is genuinely slow — a miss must stay invisible. |
+| Analytics rollups | postgres + queue | The rollup is a scheduled batch write into its own table; the trigger is a platform cron, the work is a job because it survives restarts. |
+| Leaderboard | postgres, redis if hot | A ranked query with an index is enough for most products; move the live top-N into a Redis counter set when it is read far more often than written. |
+| Invoice numbering | postgres | A gapless sequence is a transaction and a unique constraint, not a Redis counter — a lost increment is an accounting problem. |
+| Records the process was started with (plugins, seeded routes) | config | Already in `cfg`; reading them as a resource gives criteria and sorting without a second store, and every write is refused by design. |
+
+### Expiring, counting, coordinating
+
+| Case | Choice | Why |
+|---|---|---|
+| Session / OTP cache | redis | Records defined by their expiry; losing one is a re-login, not data loss. Pass the TTL again on every renewal. |
+| Password reset token | redis | Single-use and short-lived: `take(id)` hands the record to exactly one caller and throws for the second. |
+| Rate limiting | redis | A counter in a window, shared across replicas, that must expire on its own. |
+| Counters (views, usage quotas) | redis, reconciled to postgres | Increment in Redis for speed; the billable total belongs in the database, written periodically. |
+| Presence / typing indicators | redis | Sub-minute TTL plus pub/sub; nothing is worth persisting. |
+| Distributed lock | redis, or the owning resource's `lock` | Redis when the lock guards a process or a third party; the Postgres/Mongo resource's own `lock`/`unlock` when it guards its rows. |
+| Idempotency keys for an API | redis | The memory only has to outlive the retry window, and expiry is the cleanup. |
+| Webhook signature nonce cache | redis | Replay protection is exactly a key with a TTL. |
+| Handshake state in a single-process dev app | static | In-process `Map` with no database; wrong the moment there are two replicas. |
+| Fixtures / seeded demo data | static | Records reachable through the context with nothing behind them. |
+
+### Client side
+
+| Case | Choice | Why |
+|---|---|---|
+| Wizard draft | state (`single: true`) | It belongs to the screen until submitted; only the final submit is a server write. |
+| Shopping cart | state, plus postgres when it must persist | Anonymous cart lives on the client; a cart that survives a device change is a database record keyed by user. |
+| Optimistic list updates | state | The store the screen binds to, re-validated by the server on write. |
+| Notifications feed | postgres, delivered live over sockets | Rows with read/unread state that page; `state` mirrors them for rendering, it does not own them. |
+| Offline cache of server records | client (`web-db` in the browser) | Must survive a reload and a lost connection; reads walk the store, so keep the set small and re-sync from the server. |
+| Remembered UI preferences (filters, layout) | client | A handful of records per user that must outlive the tab, with nothing on the server worth a row. |
+
+### Files and bytes
+
+| Case | Choice | Why |
+|---|---|---|
+| File upload | storage + postgres | Bytes to the bucket, the record (url, size, mime, owner) in the database — a bucket has no index to query. |
+| File post-processing (thumbnails, virus scan) | queue | Survives a restart, retried against tools that fail transiently, and the user must not wait for it. |
+| PDF / report generation | queue | Multi-second CPU work whose result is a stored file; return a job id, deliver the file when it exists. |
+| GDPR data export | queue + storage | Minutes of reads across every resource, produced once, downloaded later from a bucket. |
+| OCR | queue + llm/model call | External, slow, retried — every reason on the list at once. |
+
+### Asynchronous work and third parties
+
+| Case | Choice | Why |
+|---|---|---|
+| Long CSV / JSON import | queue, staged in postgres | The user cannot hold a request open for thousands of rows, and a half-finished import must be resumable. |
+| Bulk email | queue | Thousands of provider calls, each retried independently; one bad address must not fail the batch. |
+| Transactional email (one recipient, one event) | inline | A single provider call inside the request; queue it only if the send is on a user's critical path and the provider is slow. |
+| Payment capture | queue with idempotent job ids | Retried against a third party, must survive a restart, must never double-charge — derive the job id from the payment. |
+| Third-party sync / reconciliation | queue, triggered by platform cron | Recurring, long, retried; the framework has no scheduler, so a `CronJob` enqueues it. |
+| Webhook fan-out | queue, one job per subscriber | Per-endpoint retries and backoff; a slow subscriber must not delay the others. |
+| Scheduled digest | queue, triggered by platform cron | Same shape as any recurring batch — cron enqueues, the worker sends. |
+| Scheduled reminders | postgres row + cron sweep, or `JobOptions.delay` | Use `delay` for a one-shot minutes-away nudge; anything cancellable or far in the future is a row a periodic sweep picks up. |
+| Inbound webhook handling | inline ack, queue the work | Answer 2xx immediately, then process — a third party's retry policy is not a design input for your handler. |
+| Cache warmup after a deploy | queue, or nothing | Usually not worth it: let the first requests populate the cache unless a measured cold-start hurts. |
+
+### Model-driven features
+
+| Case | Choice | Why |
+|---|---|---|
+| Chat with an assistant | agent, streamed inline; postgres for the transcript | The user is watching, so stream rather than queue; persist the conversation as ordinary records. |
+| Content moderation by model | llm + queue | Every rule that can be written down stays a rule; the model handles the rest, off the request path. |
+| Translation of stored content | llm + queue | Batch work over many records, paid per attempt, retried carefully — never on a page render. |
+| Recommendations refresh | llm or postgres batch + queue | A periodic recompute whose output is stored; the read path only ever reads the stored result. |
+| Summarizing a long document on demand | llm inline if streamed, else queue | A single streamed `ask` keeps the user informed; a pipeline over sections is queue work. |
+
+## Related
+
+- [[resource]] — the contract every option implements, and the criteria language they share
+- [[postgres-resource]], [[mongo-resource]], [[redis-resource]], [[static-resource]],
+  [[state]], [[client-resource]], [[web-db]], [[config]], [[storage-resource]] — the backends
+- [[queue]], [[redis-queue]] — job queues and the worker process
+- [[llm]], [[agent]] — model-driven work
+- [[reuse-code]] — find the `@owlmeans/*` package before designing anything new

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;;;;;;;;GAWG;AACH,oBAAY,cAAc;IACxB,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,cAAc,UAAU,cAAc,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CA6CjH,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;;;;;;;;GAWG;AACH,oBAAY,cAAc;IACxB,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,cAAc,UAAU,cAAc,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAsBjH,CAAA"}

package/build/consts.js

@@ -31,34 +31,11 @@ export const createListSchema = (schema) => ({
                 additionalProperties: false,
             }
         },
-        pager: {
-            type: 'object',
-            properties: {
-                sort: {
-                    type: 'array',
-                    items: {
-                        oneOf: [
-                            { type: 'string' },
-                            {
-                                type: 'array', items: [
-                                    { type: 'string' },
-                                    { type: 'boolean', nullable: true }
-                                ], minItems: 1, maxItems: 2
-                            }
-                        ]
-                    },
-                    nullable: true
-                },
-                page: { type: 'number', nullable: true },
-                size: { type: 'number', nullable: true },
-                total: { type: 'number', nullable: true }
-            },
-            required: [],
-            nullable: true,
-            additionalProperties: false,
-        }
+        total: { type: 'number' },
+        page: { type: 'number', nullable: true },
+        size: { type: 'number', nullable: true }
     },
-    required: ['items'],
+    required: ['items', 'total'],
     additionalProperties: false,
 });
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,6BAAW,CAAA;IACX,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAA2B,MAAyB,EAAiC,EAAE,CAAC,CAAC;IACvH,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,GAAG,MAAM;gBACT,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACtC,GAAG,MAAM,CAAC,UAAU;iBACrB;gBACD,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACrE,oBAAoB,EAAE,KAAK;aAC5B;SACF;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE;wBACL,KAAK,EAAE;4BACL,EAAE,IAAI,EAAE,QAAQ,EAAE;4BAClB;gCACE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;oCACpB,EAAE,IAAI,EAAE,QAAQ,EAAE;oCAClB,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;iCACpC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;6BAC5B;yBACF;qBACF;oBACD,QAAQ,EAAE,IAAI;iBACf;gBACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACxC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACxC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC1C;YACD,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,KAAK;SAC5B;KACF;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;IACnB,oBAAoB,EAAE,KAAK;CAC5B,CAAC,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,6BAAW,CAAA;IACX,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAA2B,MAAyB,EAAiC,EAAE,CAAC,CAAC;IACvH,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,GAAG,MAAM;gBACT,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACtC,GAAG,MAAM,CAAC,UAAU;iBACrB;gBACD,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACrE,oBAAoB,EAAE,KAAK;aAC5B;SACF;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACxC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;KACzC;IACD,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC;IAC5B,oBAAoB,EAAE,KAAK;CAC5B,CAAC,CAAA"}

package/build/helper.d.ts

@@ -1,4 +1,2 @@
-import type { ListCriteria, ListOptions } from './types.js';
-export declare const prepareListOptions: (defPageSize?: number, criteria?: ListOptions | ListCriteria, opts?: ListOptions) => ListOptions;
 export declare const filterObject: <T extends {}>(obj: T, keep?: string[]) => T;
 //# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,YAAY,CAAA;AAEtE,eAAO,MAAM,kBAAkB,iBAAiB,MAAM,aAAkB,WAAW,GAAG,YAAY,SAAS,WAAW,KAAG,WAwBxH,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,MAAM,EAAE,KAAG,CAMxD,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,MAAM,EAAE,KAAG,CAMxD,CAAA"}

package/build/helper.js

@@ -1,27 +1,3 @@
-export const prepareListOptions = (defPageSize = 10, criteria, opts) => {
-    if (opts == null) {
-        if (criteria == null) {
-            criteria = {};
-            opts = {};
-        }
-        else if ('criteria' in criteria || 'pager' in criteria) {
-            /**
-             * Both keys have to be read off the original object before it's reassigned —
-             * reading `pager` after narrowing to `.criteria` silently drops the pager.
-             */
-            const options = criteria;
-            opts = { pager: options.pager };
-            criteria = (options.criteria ?? {});
-        }
-    }
-    const size = (opts?.pager?.size ?? defPageSize);
-    const pager = {
-        sort: opts?.pager?.sort,
-        page: opts?.pager?.page ?? 0,
-        size, total: 0
-    };
-    return { criteria: criteria, pager };
-};
 export const filterObject = (obj, keep) => Object.entries(obj).reduce((obj, [key, value]) => {
     if (value == null && !keep?.includes(key)) {
         return obj;

package/build/helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAW,GAAW,EAAE,EAAE,QAAqC,EAAE,IAAkB,EAAe,EAAE;IACrI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,QAAQ,GAAG,EAAE,CAAA;YACb,IAAI,GAAG,EAAE,CAAA;QACX,CAAC;aAAM,IAAI,UAAU,IAAI,QAAQ,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;YACzD;;;eAGG;YACH,MAAM,OAAO,GAAG,QAAuB,CAAA;YACvC,IAAI,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAA;YAC/B,QAAQ,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAiB,CAAA;QACrD,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,WAAW,CAAC,CAAA;IAC/C,MAAM,KAAK,GAAc;QACvB,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;QACvB,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC;QAC5B,IAAI,EAAE,KAAK,EAAE,CAAC;KACf,CAAA;IAED,OAAO,EAAE,QAAQ,EAAE,QAAwB,EAAE,KAAK,EAAE,CAAA;AACtD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAe,GAAM,EAAE,IAAe,EAAK,EAAE,CACvE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;IAC/C,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC,EAAE,EAAO,CAAC,CAAA"}
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAe,GAAM,EAAE,IAAe,EAAK,EAAE,CACvE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;IAC/C,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC,EAAE,EAAO,CAAC,CAAA"}

package/build/index.d.ts

@@ -2,6 +2,7 @@ export * from './errors.js';
 export * from './consts.js';
 export * from './service.js';
 export * from './helper.js';
+export * from './utils/query.js';
 export * from './migration.js';
 export type * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,mBAAmB,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,mBAAmB,YAAY,CAAA"}

package/build/index.js

@@ -2,5 +2,6 @@ export * from './errors.js';
 export * from './consts.js';
 export * from './service.js';
 export * from './helper.js';
+export * from './utils/query.js';
 export * from './migration.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA"}