@owlmeans/resource 0.1.18-rc.5 → 0.1.18-rc.7

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/resource",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.500Z",
+  "version": "0.1.18-rc.7",
+  "generatedAt": "2026-08-24T21:14:00.098Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,13 +8,13 @@ user-invocable: false
 # @owlmeans/resource
 
 **Layer:** Core
-**Install:** `"@owlmeans/resource": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/resource": "^0.1.18-rc.7"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`save`/`create`/`update`/`delete`/`pick`. |
+| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`save`/`create`/`update`/`delete`/`pick`. `list(criteria?, opts?)` paginates through `opts.pager: { page, size, sort }` — there is no `limit`. |
 | `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. |
 | `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`. |
@@ -38,8 +38,42 @@ import type { Resource } from '@owlmeans/resource'
 interface Project { id: string; name: string; entityId: string }
 const projects = ctx.resource<Resource<Project>>('projects')
 const { items } = await projects.list({ entityId: 'abc' })
+
+// Pagination and sort ride under `pager` in the SECOND argument — there is NO `limit`,
+// and neither `page` nor `size` exists at the top level of either argument:
+const page2 = await projects.list(
+  { entityId: 'abc' },
+  { pager: { page: 1, size: 20, sort: ['createdAt'] } }
+)
+// page2.pager echoes { page, size, total } for building pagination UI.
 ```
 
+### 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` | create-or-replace |
+| `update(record, opts?)` | `Partial<T> → T` | replaces the whole record; throws `UnknownRecordError` |
+
+A **read** takes the id first, plus an optional field to look it up by (`opts` is that field name,
+or `{ field, ttl }`):
+
+| Call | Signature | Notes |
+|---|---|---|
+| `load(id, field?, opts?)` | `string → T \| null` | the miss-tolerant read |
+| `get(id, field?, opts?)` | `string → T` | throws `UnknownRecordError` instead of returning `null` |
+| `list(criteria?, opts?)` | `→ { items, pager }` | |
+| `delete(id \| record, opts?)` | `→ T \| null` | returns what it removed |
+| `pick(id \| record, opts?)` | `→ T` | **also deletes** — it is `delete` that throws on a miss, never a read |
+
+Every method returns the record(s) themselves, never a driver result object — there is no
+`rowsAffected`/`rowCount` anywhere on this contract.
+
 ## The migration framework
 
 Migrations are **automatic on app setup**: a backend runs them inside the resource's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/resource",
-  "version": "0.1.18-rc.5",
+  "version": "0.1.18-rc.7",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,8 +22,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/context": "^0.1.18-rc.5",
-    "@owlmeans/error": "^0.1.18-rc.5",
+    "@owlmeans/context": "^0.1.18-rc.6",
+    "@owlmeans/error": "^0.1.18-rc.6",
     "@scure/base": "^2.3.0"
   },
   "peerDependencies": {