@t4h.framework/orm 0.4.0 → 0.6.0

package/.ai/skills/framework-orm/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   exists), Ref and RefCollection, query operators, constraint validation, ORM
   activities, and ORMClaim wiring. Use when defining database entities, persisting
   or querying rows in workflows, implementing ORMClaim providers, testing ORM
-  activities with Claim.run, or working in packages/orm.
+  workflows with TestWorkflowEnvironment, or working in packages/orm.
 ---
 
 # @t4h.framework/orm
@@ -41,11 +41,9 @@ Node `>=22`. See [README.md](../../../README.md).
 |-------|------|
 | **ORM** | High-level API; applies defaults + constraints before activities |
 | **Ref** / **RefCollection** | Row handles returned by create/find |
-| **Activities** | `SyncActivity` classes delegating to `ORMClaim` |
+| **Activities** | Shipped, replay-safe activities the `ORM`/`Ref` APIs drive; delegate to `ORMClaim` |
 | **ORMClaim** | Abstract claim; runtime provides concrete DB implementation |
 
-All ORM activities use `new Claim({ orm: ORMClaim })` and delegate in `run()`.
-
 ---
 
 ## Defining entities
@@ -171,7 +169,7 @@ const exists = await orm.exists(User, {
 ### Ref operations
 
 ```typescript
-const snapshot = await userRef.getSnapshot() // T | null — entity instance via Reflect.construct
+const snapshot = await userRef.getSnapshot() // T | null — entity instance
 await userRef.update({ name: 'Jane' })         // partial patch only
 await userRef.remove()
 ```
@@ -260,13 +258,13 @@ abstract class ORMClaim<R extends SerializableRowRef> {
 
 Activity inputs always include `orm` + `table`; create adds `data[]`, find adds `where` (+ optional `orderBy`/`limit`/`offset`), snapshot/update/remove add `ref` (opaque `Serializable` row handle). Update also includes partial `data`.
 
-Access claim-backed activity logic only inside `Claim.run` or workflow `History.run` context.
+The `ORM`/`Ref` calls run inside a workflow (the runtime, or `TestWorkflowEnvironment` in tests, provides the reconciler context).
 
 ---
 
 ## Activities
 
-All extend `SyncActivity` and delegate to `ORMClaim`:
+These are the **shipped, replay-safe activities** the `ORM`/`Ref` APIs drive for you (you can also pass them to `History.reconciler` directly). Never define your own:
 
 | Activity | Input | Output |
 |----------|-------|--------|
@@ -283,7 +281,7 @@ Prefer **`ORM` / `Ref` APIs** in workflow code — they apply constraints and re
 
 ## Workflow example
 
-From `examples/basic/src/workflows/orm.ts` — define entities, instantiate `ORM` with `connectionString` + `entities`, use inside `Workflow`:
+Define entities, instantiate `ORM` with `connectionString` + `entities`, and use it inside a `Workflow`:
 
 ```typescript
 export const orm = new ORM({ connectionString: '...', entities: [User] })
@@ -303,13 +301,29 @@ Ensure the runtime provides `ORMClaim`.
 
 ## Testing
 
-Run: `yarn test` in `packages/orm`.
+Test the **workflow** with `TestWorkflowEnvironment` from
+`@t4h.framework/core/testing`, mocking `ORMClaim` — the single claim the ORM
+activities resolve. Provide the methods your workflow triggers (`create`, `find`,
+`findOne`, `getSnapshot`, `update`, `remove`). See the **framework-workflow-testing**
+skill for the harness API.
+
+```typescript
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
+import { ORMClaim } from '@t4h.framework/orm'
+
+const mockCreate = vi.fn().mockImplementation(async () => [{ id: 1 }])
+const mockFindOne = vi.fn().mockImplementation(async () => ({ id: 1, name: 'John' }))
 
-**ORM / Ref unit tests** — mock `History.bind` by activity name (`ORMCreateActivity`, `ORMFindOneActivity`, etc.) per `src/models/__tests__/ORM.spec.ts`. Assert `ConstraintError` before activities run: `expect(mockCreate).not.toHaveBeenCalled()`.
+const env = TestWorkflowEnvironment.create({ now: 0 })
 
-**Activity unit tests** — wrap `activity.run(input)` in `Claim.run([{ provide: ORMClaim, value: mockClaim }], fn)` per `src/activities/__tests__/ORMCreateActivity.spec.ts`.
+await env.execute(workflow, input, {
+  claims: [mockClaim(ORMClaim, { create: mockCreate, findOne: mockFindOne })],
+})
+```
 
-**Workflow integration** — `WorkflowTesting.run` with a mocked `ORMClaim` provider (see **framework-core** skill).
+Constraint/validation errors are applied by the `ORM`/`Ref` layer before the
+activity runs, so you can assert an invalid input rejects without the claim being
+called: `expect(mockCreate).not.toHaveBeenCalled()`.
 
 ---
 
@@ -320,6 +334,6 @@ Run: `yarn test` in `packages/orm`.
 3. Use **`orm` / `Ref` APIs** in workflows — not raw SQL or direct claim calls.
 4. Handle **`ConstraintError`**; validation runs before activities.
 5. **`Ref.update`** is partial; **`getSnapshot`** returns entity instances.
-6. Test with **`History.bind` mocks** or **`Claim.run` + ORMClaim mock**; only use exported APIs.
+6. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim(ORMClaim, ...)`**; only use exported APIs.
 
-See also: `packages/orm/README.md`, `examples/basic/src/workflows/orm.ts`.
+See also: `packages/orm/README.md`; **framework-workflow-testing** for the test harness.

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+import type { ClaimProvider } from '@t4h.framework/core';
+import { ORMClaim } from '../claims/ORMClaim.js';
+export declare function createInMemoryORMClaim(): ClaimProvider<ORMClaim<string>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGxD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAUhD,wBAAgB,sBAAsB,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CA2DxE"}

package/dist/testing/index.js

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { mockClaim } from '@t4h.framework/core/testing';
+import { ORMClaim } from '../claims/ORMClaim.js';
+export function createInMemoryORMClaim() {
+    const tables = new Map();
+    const table = (name) => {
+        let rows = tables.get(name);
+        if (!rows) {
+            rows = new Map();
+            tables.set(name, rows);
+        }
+        return rows;
+    };
+    const claim = {
+        find(input) {
+            const rows = [...table(input.table).values()];
+            return rows
+                .filter(row => matchesWhere(row, input.where))
+                .slice(input.offset ?? 0, input.limit ? (input.offset ?? 0) + input.limit : undefined)
+                .map(row => row.id);
+        },
+        create(input) {
+            const rows = table(input.table);
+            return input.data.map(row => {
+                const id = String(row.id ?? randomUUID());
+                const snapshot = { ...row, id };
+                rows.set(id, snapshot);
+                return id;
+            });
+        },
+        getSnapshot(input) {
+            return table(input.table).get(input.ref) ?? null;
+        },
+        update(input) {
+            const rows = table(input.table);
+            const current = rows.get(input.ref);
+            if (!current)
+                return;
+            rows.set(input.ref, { ...current, ...input.data });
+        },
+        remove(input) {
+            table(input.table).delete(input.ref);
+        },
+    };
+    return mockClaim(ORMClaim, claim);
+}
+function matchesWhere(row, where) {
+    if (!where)
+        return true;
+    return Object.entries(where).every(([key, expected]) => row[key] === expected);
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/orm",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "ORM module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/orm",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -35,12 +35,12 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.6.0",
+    "@t4h.framework/core": "^0.9.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.6.0"
+    "@t4h.framework/core": "^0.9.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {