@t4h.framework/orm 0.11.3 → 0.11.5

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

@@ -1,362 +1,133 @@
 ---
 name: framework-orm
 description: >-
-  Guides correct use of @t4h.framework/orm in T4H Framework workflows: entity
-  decorators (@Entity, @Property, @Index), the ORM model (create, upsert, find, findOne,
-  exists, delete), 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
-  workflows with TestWorkflowEnvironment, or working in packages/orm.
+  Guides the use of @t4h.framework/orm in T4H Framework workflows: entity
+  decorators (@Entity, @Property, @Index, @ManyToOne, @OneToMany), the ORM
+  class (create, upsert, find, findOne, exists, delete), Ref, RefCollection and
+  MapCollection, getSnapshot with populate, where operators ($in, $like, $or,
+  ...), ConstraintError, and ORMClaim. Use when you define database entities,
+  read or write rows in a workflow, model relations between tables, give or
+  mock ORMClaim in a test with TestWorkflowEnvironment, or write an ORMClaim
+  implementation.
 ---
 
 # @t4h.framework/orm
 
-ORM activities, claim, and models for database operations within workflows. Package path: `framework/packages/orm`. Peer dependency: `@t4h.framework/core`.
+Each `ORM`, `Ref` and `RefCollection` call is an activity recorded in the
+workflow history. The runtime gives the database through `ORMClaim`.
 
-Import from `src/orm.ts` only — do not reference unexported modules:
+## Define an entity
 
-```typescript
-import {
-  Entity, Property, Index, ORM, Ref, RefCollection,
-  ORMClaim, ConstraintError,
-  ORMCreateActivity, ORMFindActivity, ORMFindOneActivity,
-  ORMGetSnapshotActivity, ORMUpdateActivity, ORMRemoveActivity,
-  ORMDeleteActivity,
-  getEntityMetadata, getEntityTableName, getEntityProperties,
-  type EntityInsertData, type EntityPartialData, type FindWhere,
-  type SerializableCreateInput, type SerializableFindInput,
-  type SerializableGetSnapshotInput, type SerializableUpdateInput,
-  type SerializableRemoveInput, type SerializableDeleteInput,
-} from '@t4h.framework/orm'
-```
-
-Node `>=22`. See [README.md](../../../README.md).
-
----
-
-## Architecture
-
-`Workflow` → `ORM` / `Ref` methods (`History.bind` on ORM activities) → `ORMClaim` (runtime database adapter).
-
-| Layer | Role |
-|-------|------|
-| **ORM** | High-level API; applies defaults + constraints before activities |
-| **Ref** / **RefCollection** | Row handles returned by create/find |
-| **Activities** | Shipped, replay-safe activities the `ORM`/`Ref` APIs drive; delegate to `ORMClaim` |
-| **ORMClaim** | Abstract claim; runtime provides concrete DB implementation |
-
----
-
-## Defining entities
-
-Enable decorator metadata in the project `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-Import `reflect-metadata` where decorators are evaluated (Property decorator imports it).
-
-### @Entity
+1. Enable `experimentalDecorators` and `emitDecoratorMetadata` in
+   `tsconfig.json`.
+2. Decorate the class with `@Entity({ tableName })` (required option) and each
+   column with `@Property`.
+3. Declare `id` and each property with a `default` as optional. Also set
+   `nullable: true` on `id`: the store sets it.
 
 ```typescript
 @Entity({ tableName: 'users' })
 class User {
-  @Property({ type: 'string' })
-  public name!: string
+  @Property({ type: 'uuid', nullable: true })
+  public id?: string
 
-  @Property({ type: 'string' })
+  @Property({ type: 'string', index: true })
   public email!: string
 
   @Property({ type: 'boolean', default: true })
-  public active!: boolean
+  public active?: boolean
 }
 ```
 
-- `tableName` is optional; defaults to the class name (`User` → `"User"`).
-- Use `getEntityTableName(User)` or rely on ORM to resolve the table name.
-
-### @Property
-
-Options: `type?`, `nullable?` (default required), `default?`, `index?` (adds index metadata).
+## Create the ORM once
 
-Omit `type` to infer from design metadata (`String`→`string`, `Number`→`number`, etc.). Declare domain types (`uuid`) explicitly. Validated types: `string`, `uuid`, `number`, `boolean`, `array`, `date`, `object`. No `type` → skip type validation.
-
-### @Index
-
-Class-level composite indexes:
-
-```typescript
-@Index({ properties: ['tenantId', 'email'], name: 'accounts_tenant_email_idx' })
-class Account { /* ... */ }
-```
-
-`properties` must be non-empty or the decorator throws. Per-property `@Property({ index: true })` also registers `{ properties: [propertyKey] }`.
-
----
-
-## ORM configuration
-
-`ORM` extends `SerializableClass` — instances can be serialized for workflow persistence. `connectionString` is the `Secret` an `EnvDesign` entry declared `type: Secret` hands the workflow (a string is a `tsc` error); the host reads the value where each query runs.
+Declare `DATABASE_URL: { type: Secret }` with `EnvDesign` in
+`src/constants/environments.ts`, and create the `ORM` at module level, not in
+the workflow function:
 
 ```typescript
 import { environments } from '../constants/environments.js'
 
-const orm = new ORM({
-  connectionString: environments.DATABASE_URL, // Secret
-  entities: [User, Product],
-})
-```
-
-- `entities`: array of entity **constructors** (decorated classes).
-- `config.entities` stores resolved `EntityMetadata` (table name, properties map, indexes).
-
-Restore from serialized state:
-
-```typescript
-const orm = await ORM.fromSerializable(serialized, v => v)
-```
-
----
-
-## CRUD in workflows
-
-ORM methods bind activities via `History.bind` — calls inside a workflow are **reconciler-driven** (replay-safe).
-
-### Create
-
-```typescript
-// Single row → Ref<T>
-const userRef = await orm.create(User, {
-  name: 'John',
-  email: 'john@example.com',
-  active: true,
-})
-
-// Batch → RefCollection<T>
-const usersRef = await orm.create(User, [
-  { name: 'Alice', email: 'alice@example.com', active: true },
-  { name: 'Bob', email: 'bob@example.com', active: true },
-])
-```
-
-Defaults are applied before persistence (`applyDefaultProperties`). Omitted fields with `@Property({ default })` are filled in.
-
-### Upsert
-
-```typescript
-// Single row → Ref<T>; array → RefCollection<T>
-const userRef = await orm.upsert(
-  User,
-  { email: 'john@example.com', name: 'John', active: true },
-  { conflictOn: ['email'] },
-)
-```
-
-Rows are validated like `create`. If a row matching `conflictOn` (equality on every listed property) exists, only the passed fields are written; defaults apply on insert only. Every row must have a value for each `conflictOn` property (`ConstraintError` otherwise), and `conflictOn` cannot be empty. The call is a single `ORMUpsertActivity` backed by `ORMClaim.upsert`, which has a default (`find`, then `create` or `update`) — mock `upsert` in tests, or `find`/`create`/`update` if the mock extends `ORMClaim`. A retry after a crash updates instead of duplicating, but it is not atomic across workflows: concurrent writes of the same key may both insert.
-
-### Find
-
-```typescript
-const userRef = await orm.findOne(User, {
-  where: { email: 'john@example.com' },
-  orderBy: { name: 'asc' },
-}) // Ref<User> | null
-
-const usersRef = await orm.find(User, {
-  where: { active: true },
-  orderBy: { name: 'asc' },
-  limit: 10,
-  offset: 0,
-}) // RefCollection<User>
-
-const exists = await orm.exists(User, {
-  where: { email: 'john@example.com' },
-}) // boolean (delegates to findOne)
-
-const deleted = await orm.delete(User, {
-  where: { active: false },
-}) // number — deletes every match; `{}` empties the table
-```
-
-`findOne` activity internally calls `claim.find` with `limit: 1`.
-
-### Ref operations
-
-```typescript
-const snapshot = await userRef.getSnapshot() // T | null — entity instance
-await userRef.update({ name: 'Jane' })         // partial patch only
-await userRef.remove()
-```
-
-`getSnapshot` returns `null` when the row no longer exists. `update` validates only keys present in the patch.
-
-**RefCollection:** `toArray()`, `length`, `at(i)`, async `forEach`/`map`/`filter`, `Symbol.iterator`.
-
----
-
-## Query operators
-
-`where` uses `FindWhere<T>` — implicit equality or operator objects:
-
-```typescript
-await orm.find(User, {
-  where: {
-    name: 'John',                    // $eq (implicit)
-    active: { $ne: false },
-    email: { $like: '%@example%' },
-    age: { $gte: 18, $lt: 65 },
-    status: { $in: ['active', 'pending'] },
-    $or: [{ name: 'Alice' }, { name: 'Bob' }],
-    $and: [{ active: true }, { age: { $gte: 18 } }],
-  },
+export const orm = new ORM({
+  connectionString: environments.DATABASE_URL,
+  entities: [User, Post],
 })
 ```
 
-Available operators: `$eq`, `$ne`, `$in`, `$nin`, `$not`, `$gt`, `$gte`, `$lt`, `$lte`, `$like`, `$ilike`, `$and`, `$or`.
-
----
-
-## Constraint validation
-
-Validation runs in the ORM library (`ORM.create`, `ORM.upsert` and `Ref.update`), **not** in `ORMClaim` implementations. Failures throw `ConstraintError`.
-
-### Create pipeline
-
-1. `applyDefaultProperties` — fills `default` for `undefined` fields
-2. `assertPropertyTypeConstraint` — validates declared types
-3. `assertNonNullablePropertyConstraint` — required fields must be present
-
-### Update pipeline
-
-1. Defaults only for keys present in the patch
-2. Same asserts, scoped to patch keys via `{ keys: Object.keys(data) }`
-
-### Handling errors
+## Read and write
 
 ```typescript
-import { ConstraintError, ORM } from '@t4h.framework/orm'
+const userRef = await orm.create(User, { email: input.email }) // Ref<User>
+const found = await orm.findOne(User, { where: { email: input.email } }) // Ref<User> | null
+const active = await orm.find(User, { where: { active: true }, limit: 10 }) // RefCollection<User>
 
-try {
-  await orm.create(User, { email: 'bad' } as EntityInsertData<User>)
-} catch (error) {
-  if (error instanceof ConstraintError) {
-    // e.g. 'Property "name" is required'
-    // e.g. 'Property "name" must be of type string'
-  }
-}
+const user = await userRef.getSnapshot() // User | null
+await userRef.update({ active: false }) // partial patch
+const snapshots = await active.getSnapshots() // one activity for all refs
 ```
 
-Constraint checks run **before** activities are invoked — failed creates/updates never reach `ORMClaim`.
+## Relations
 
----
-
-## ORMClaim (runtime dependency)
-
-Runtime must register a concrete implementation:
+The `@ManyToOne` side owns the column and is a `Ref<T>`. The `@OneToMany` side
+is a lazy `MapCollection<T>`. Read related rows in the same activity with
+`populate`:
 
 ```typescript
-{ provide: ORMClaim, value: new MyORMClaimImpl() }
-```
-
-Contract:
-
-```typescript
-abstract class ORMClaim<R extends SerializableRowRef> {
-  abstract find(input: SerializableFindInput): R[] | Promise<R[]>
-  abstract create(input: SerializableCreateInput): R[] | Promise<R[]>
-  abstract getSnapshot(input: SerializableGetSnapshotInput<R>): SerializedRow | null | Promise<SerializedRow | null>
-  abstract update(input: SerializableUpdateInput<R>): void | Promise<void>
-  abstract remove(input: SerializableRemoveInput<R>): void | Promise<void>
-  upsert(input: SerializableUpsertInput): Promise<R[]> // default: find, then create/update; override for a native upsert
-  abstract delete(input: SerializableDeleteInput): number | Promise<number>
-}
-```
-
-Activity inputs always include `orm` + `table`; create adds `data[]`, find and delete add `where` (find also takes optional `orderBy`/`limit`/`offset`), snapshot/update/remove add `ref` (opaque `Serializable` row handle). Update also includes partial `data`. Upsert adds `conflictOn` and `data: { insert, update }[]` — `insert` is the full row with defaults, `update` only the caller's fields; return refs in input order.
-
-The `ORM`/`Ref` calls run inside a workflow (the runtime, or `TestWorkflowEnvironment` in tests, provides the reconciler context).
-
----
-
-## Activities
-
-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 |
-|----------|-------|--------|
-| `ORMCreateActivity` | `SerializableCreateInput` | `SerializableRowRef[]` |
-| `ORMFindActivity` | `SerializableFindInput` | `SerializableRowRef[]` |
-| `ORMFindOneActivity` | `SerializableFindInput` | `SerializableRowRef \| null` |
-| `ORMGetSnapshotActivity` | `SerializableGetSnapshotInput` | `SerializedRow \| null` |
-| `ORMUpdateActivity` | `SerializableUpdateInput` | `void` |
-| `ORMRemoveActivity` | `SerializableRemoveInput` | `void` |
-| `ORMDeleteActivity` | `SerializableDeleteInput` | `number` |
-
-Prefer **`ORM` / `Ref` APIs** in workflow code — they apply constraints and return typed handles. Use activities directly only for advanced/testing scenarios.
-
----
-
-## Workflow example
-
-Define entities, instantiate `ORM` with `connectionString` + `entities`, and use it inside a `Workflow`:
-
-```typescript
-export const orm = new ORM({ connectionString: environments.DATABASE_URL, entities: [User] })
-
-export const ormWorkflow = new Workflow({ id: 'orm' }, async () => {
-  await orm.create(User, { name: 'John', email: 'john@example.com', age: 20 })
-  const user = await orm.findOne(User, { where: { email: 'john@example.com' } })
-  await user?.update({ name: 'John Updated' })
-  await user?.remove()
-  return { user }
-})
-```
-
-Ensure the runtime provides `ORMClaim`.
-
----
-
-## Testing
-
-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`, `upsert`, `find`,
-`findOne`, `getSnapshot`, `update`, `remove`). See the **framework-workflow-testing**
-skill for the harness API.
+@OneToMany(() => Post, post => post.author)
+public posts!: MapCollection<Post>
+
+@ManyToOne(() => User)
+public author!: Ref<User>
+
+const user = await userRef.getSnapshot({ populate: ['posts.comments'] })
+const titles = await user?.posts.map(post => post.title)
+```
+
+## Traps
+
+- `getSnapshot()` returns `null` when the row no longer exists. A populated
+  `@ManyToOne` can also be `null`, also when the relation is not nullable.
+- A snapshot is a copy. Write through the `Ref` (`ref.update`), and use
+  `ref.load('author')` to get the `Ref` of a related row.
+- `MapCollection` is not a promise. Call a method (`toArray()`, `map()`,
+  `count()`); do not `await user.posts`.
+- `refs.map(ref => ref.getSnapshot())` runs one activity per ref. Use
+  `refs.getSnapshots()` or `populate`.
+- A populate is the output of one activity and goes into the history. Keep it
+  narrow on large relations; filter with `where` and `limit`.
+- `orm.delete(User, { where: {} })` deletes every row of the table.
+- `upsert` needs a non-empty `conflictOn` and a value for each listed property.
+  It is not atomic across workflows: two workflows can both insert.
+- A bad row throws `ConstraintError` before an activity runs.
+- Do not construct or extend the `ORM*Activity` classes. The lint rule
+  `@t4h.framework/core/no-framework-activity-in-app` rejects it. Use `ORM` and
+  `Ref`.
+- To write a relation, give a `Ref` (or the data of a new row in `create`).
+  You cannot write the `@OneToMany` side of an existing row.
+
+## Test
+
+Give `ORMClaim` with `mockClaim` and mock only what the workflow calls.
+`ORMClaim` has no `findOne` (it calls `find` with `limit: 1`), and
+`getSnapshot` on a `Ref` calls `getSnapshots`:
 
 ```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' }))
+const create = vi.fn(async () => [{ id: 1 }])
+const getSnapshots = vi.fn(async () => [{ id: 1, email: 'john@example.com' }])
 
-const env = TestWorkflowEnvironment.create({ now: 0 })
-
-await env.execute(workflow, input, {
-  claims: [mockClaim(ORMClaim, { create: mockCreate, findOne: mockFindOne })],
+await TestWorkflowEnvironment.create().execute(onboard, input, {
+  claims: [mockClaim(ORMClaim, { create, getSnapshots })],
 })
 ```
 
-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()`.
-
----
-
-## Checklist for agents
-
-1. **`@Entity` + `@Property`** with `experimentalDecorators` + `emitDecoratorMetadata`.
-2. Register entities in **`ORM({ entities: [...] })`**; runtime provides **`ORMClaim`**.
-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 workflows with **`TestWorkflowEnvironment`** + **`mockClaim(ORMClaim, ...)`**; only use exported APIs.
+## Reference
 
-See also: `packages/orm/README.md`; **framework-workflow-testing** for the test harness.
+- Overview, runtime and tests: https://tech4humans-brasil.github.io/framework/orm/
+- Entities and validation: https://tech4humans-brasil.github.io/framework/orm/entities
+- Queries, upsert, delete, operators: https://tech4humans-brasil.github.io/framework/orm/queries
+- `Ref` and `RefCollection`: https://tech4humans-brasil.github.io/framework/orm/records
+- Relations, populate, `MapCollection`: https://tech4humans-brasil.github.io/framework/orm/relations
+- Types: `node_modules/@t4h.framework/orm/dist/orm.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @t4h.framework/orm
 
+## 0.11.5
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The orm README is short and points to the docs site. The docs and the skill now match the source: the entity examples declare `id` as optional, and a test mocks `find` and `getSnapshots` of `ORMClaim`, not `findOne`.
+
+## 0.11.4
+
+### Patch Changes
+
+- [#241](https://github.com/tech4humans-brasil/framework/pull/241) [`f6b8454`](https://github.com/tech4humans-brasil/framework/commit/f6b845484d22e7c8e7240fe2e113f1cdea7c8ce3) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds seven rules to `@t4h.framework/core/eslint` and turns them on in `configs.recommended`:
+  - `no-io-in-workflow` reports `fetch` and calls to network, file, database and mail modules in a workflow and in the `constructor`, `toInput` and `toOutput` of an activity. It also reports `zlib` and `stream` calls there, because they work on the content in memory on each replay.
+  - `no-binary-subclass` reports a class that extends `Binary`.
+  - `no-framework-activity-in-app` reports `new` and `extends` on an activity of a framework package other than the core.
+  - `no-testing-import-in-source` reports an import of a `@t4h.framework/<package>/testing` entry out of a test file.
+  - `require-workflow-id` reports a `Workflow` with no `id`.
+  - `no-secret-to-string` reports a `Secret` that becomes a string.
+  - `no-literal-secret-in-authorization` reports a string literal in the `secret` or `clientSecret` field of an `Authorization`.
+
+  The package skills now name these rules in place of the text that the rules enforce. The docs and skills give each `Workflow` an `id`, read the HMAC secret from `EnvDesign`, and do not document a custom HTTP activity.
+
+- [#243](https://github.com/tech4humans-brasil/framework/pull/243) [`0ffd663`](https://github.com/tech4humans-brasil/framework/commit/0ffd663ce8369edd7b54206cb3216568ad1de471) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The README examples read each value from `environments`, an `EnvDesign` in `src/constants/environments.ts`, and pass each credential as a `Secret`. They no longer use `process.env`, the raw `env` from the core or a literal in a `Secret` field. The jwks README describes the real context fields (`signature`, `rawPayload`) and says that a token that `jwt.verify` rejects throws.
+
+- [#240](https://github.com/tech4humans-brasil/framework/pull/240) [`0606115`](https://github.com/tech4humans-brasil/framework/commit/0606115e2e0baa994e9f0ed3559ee54ecac88e44) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The skills do not repeat a rule that a lint rule, `tsc` or a runtime error already enforces. Each such rule is now one line that names the gate. The examples that broke a gate (`process.env`, `as any`, an inline secret, an `EnvDesign` in a workflow file, `ref.output` before `wait()`) are correct now.
+
+- [#226](https://github.com/tech4humans-brasil/framework/pull/226) [`e11c2ee`](https://github.com/tech4humans-brasil/framework/commit/e11c2ee0d959dff4ea1c8861ec036f9f299b743c) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - `RefCollection.filter` waits for an async predicate. Before, it kept every ref, because a pending promise is truthy. A missing relation, plan row or loaded row now throws a clear error. The `mappedBy` callback of `OneToMany` returns `Ref<unknown>` in place of `Ref<any>`.
+
 ## 0.11.3
 
 ### Patch Changes