@t4h.framework/orm 0.11.4 → 0.11.5

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

@@ -1,351 +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 the package entry `@t4h.framework/orm`. Its `exports` map has only `.`, so `tsc` rejects a deep import.
+## 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
-
-Set `experimentalDecorators` and `emitDecoratorMetadata` to `true` in the `compilerOptions` of the project `tsconfig.json`.
-
-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.
+## Create the ORM once
 
-### @Property
-
-Options: `type?`, `nullable?` (default required), `default?`, `index?` (adds index metadata).
-
-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 { /* ... */ }
-```
-
-An empty `properties` throws (`decorators/Index.ts`). Per-property `@Property({ index: true })` also registers `{ properties: [propertyKey] }`.
-
----
-
-## ORM configuration
-
-`ORM` extends `SerializableClass` — instances can be serialized for workflow persistence. `connectionString` is typed `Secret` (a string is a `tsc` error): pass the `EnvDesign` entry declared `type: Secret`. 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. An empty `conflictOn`, or a row with no value for a `conflictOn` property, throws (`ConstraintError` for a missing key, `Error` for an empty `conflictOn`). 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() }
-```
+@OneToMany(() => Post, post => post.author)
+public posts!: MapCollection<Post>
 
-Contract:
+@ManyToOne(() => User)
+public author!: Ref<User>
 
-```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>
-}
+const user = await userRef.getSnapshot({ populate: ['posts.comments'] })
+const titles = await user?.posts.map(post => post.title)
 ```
 
-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.
-
----
-
-## Activities
-
-These are the **shipped, replay-safe activities** the `ORM`/`Ref` APIs drive for you (you can also pass them to `History.reconciler` directly). `@t4h.framework/core/no-framework-activity-in-app` rejects `new` and `extends` on them:
-
-| 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.
+## 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 env = TestWorkflowEnvironment.create({ now: 0 })
+const create = vi.fn(async () => [{ id: 1 }])
+const getSnapshots = vi.fn(async () => [{ id: 1, email: 'john@example.com' }])
 
-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`** on each entity class.
-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, ...)`**.
+## 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,11 @@
 # @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

package/README.md

@@ -1,308 +1,50 @@
 # @t4h.framework/orm
 
-ORM activities, claim, and models for database operations within workflows.
+Durable, replay-safe database access for workflows. You describe tables as
+decorated classes and read and write them through `ORM`, `Ref` and
+`RefCollection`. The runtime gives the database through `ORMClaim`.
 
-## Claim
+## Installation
 
-### ORMClaim
-
-Abstract dependency for database operations. The runtime must provide a concrete implementation (e.g. PostgreSQL, SQLite).
-
-```typescript
-import { ORMClaim } from '@t4h.framework/orm'
-```
-
-### Interface
-
-```typescript
-abstract class ORMClaim<R extends SerializableRowRef> {
-  public abstract find(input: SerializableFindInput): R[] | Promise<R[]>
-  public abstract create(input: SerializableCreateInput): R[] | Promise<R[]>
-  public abstract getSnapshot(input: SerializableGetSnapshotInput<R>): SerializedRow | Promise<SerializedRow>
-  public abstract update(input: SerializableUpdateInput<R>): void | Promise<void>
-  public abstract remove(input: SerializableRemoveInput<R>): void | Promise<void>
-  public abstract getSnapshots(input: SerializableGetSnapshotsInput<R>): (SerializedRow | null)[] | Promise<(SerializedRow | null)[]>
-  public abstract delete(input: SerializableDeleteInput): number | Promise<number>
-
-  // Default: find, then create or update. Override for a native upsert.
-  public upsert(input: SerializableUpsertInput): Promise<R[]>
-}
+```bash
+npm install @t4h.framework/orm
 ```
 
-## Defining Entities
+Peer dependency: `@t4h.framework/core`. Enable `experimentalDecorators` and
+`emitDecoratorMetadata` in `tsconfig.json`.
 
-Use the `@Entity` and `@Property` decorators to define database entities:
+## Usage
 
 ```typescript
-import { Entity, Property } from '@t4h.framework/orm'
+import { Workflow } from '@t4h.framework/core'
+import { Entity, ORM, Property } from '@t4h.framework/orm'
+
+import { environments } from './constants/environments.js'
 
 @Entity({ tableName: 'users' })
 class User {
   @Property({ type: 'uuid', nullable: true })
   public id?: string
 
-  @Property({ type: 'string' })
-  public name!: string
-
   @Property({ type: 'string' })
   public email!: string
-
-  @Property({ type: 'boolean', default: true })
-  public active?: boolean
 }
-```
-
-`id` is assigned by the store on create, so declare it optional and `nullable`
-— a non-nullable property missing from the data fails
-`assertNonNullablePropertyConstraint`, and `EntityInsertData` would require you
-to pass it yourself. The same goes for any property carrying a `default`.
-
-### @Entity options
-
-```typescript
-@Entity({ tableName?: string })
-```
-
-### @Property options
-
-```typescript
-@Property({
-  type?: string,
-  nullable?: boolean,
-  default?: any,
-  index?: boolean,
-})
-```
-
-When `type` is omitted, it is inferred from the TypeScript property type if the project enables `emitDecoratorMetadata` (and imports `reflect-metadata`). Domain types such as `uuid` must be declared explicitly.
-
-If `nullable` is omitted, the property is required at runtime validation.
-
-### TypeScript configuration for entity classes
-
-Projects that define entities with `@Property()` should enable:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-## Constraints
-
-Row validation runs in the ORM library (`ORM.create`, `ORM.upsert` and `Ref.update`), not in `ORMClaim` implementations. Failed checks throw `ConstraintError`.
-
-### Pipeline
-
-**Create** (full row, after defaults):
-
-1. `applyDefaultProperties` — fills `default` for `undefined` fields
-2. `assertPropertyTypeConstraint` — validates declared types
-3. `assertNonNullablePropertyConstraint` — required fields must be present
-
-**Update** (partial patch only):
-
-1. Defaults only for keys present in the patch
-2. Same asserts, scoped to patch keys
-
-### Supported property types
-
-`string`, `uuid`, `number`, `boolean`, `array`, `date`, `object`. Properties without `type` skip type validation.
-
-### Example
-
-```typescript
-import { ConstraintError, ORM } from '@t4h.framework/orm'
-
-try {
-  await orm.create(User, { email: 'taken@example.com' })
-} catch (error) {
-  if (error instanceof ConstraintError) {
-    // handle validation failure
-  }
-}
-```
-
-## ORM Model
-
-The `ORM` class provides a high-level API for database operations. It wraps the underlying activities (`ORMCreateActivity`, `ORMFindActivity`, `ORMFindOneActivity`).
-
-### Creating records
-
-The connection string is a `Secret`, so `tsc` rejects a string. Declare it with `type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
-
-```typescript
-// src/constants/environments.ts
-import { EnvDesign, Secret } from '@t4h.framework/core'
-
-export const environments = EnvDesign({
-  DATABASE_URL: { type: Secret },
-})
-```
-
-```typescript
-import { ORM } from '@t4h.framework/orm'
-
-import { environments } from './constants/environments.js'
 
 const orm = new ORM({
   connectionString: environments.DATABASE_URL,
   entities: [User],
 })
 
-const userRef = await orm.create(User, {
-  name: 'John',
-  email: 'john@example.com',
-  active: true,
-})
-```
-
-### Batch create
-
-```typescript
-const usersRef = await orm.create(User, [
-  { name: 'Alice', email: 'alice@example.com', active: true },
-  { name: 'Bob', email: 'bob@example.com', active: true },
-])
-```
-
-### Upsert
-
-```typescript
-// Inserts, or updates the row with the same email
-const userRef = await orm.upsert(
-  User,
-  { email: 'john@example.com', name: 'John', active: true },
-  { conflictOn: ['email'] },
-)
-```
-
-Pass an array for a batch (returns a `RefCollection`). On update only the fields you passed are written; defaults apply on insert only. The call runs as a single `ORMUpsertActivity`, so a retry after a crash updates instead of duplicating; it is not atomic across workflows, so concurrent writes of the same key may both insert.
-
-### Finding records
-
-```typescript
-const userRef = await orm.findOne(User, {
-  where: { email: 'john@example.com' },
-})
+export const onboard = new Workflow({ id: 'onboard' }, async () => {
+  const userRef = await orm.create(User, { email: 'john@example.com' })
 
-const usersRef = await orm.find(User, {
-  where: { active: true },
-  orderBy: { name: 'asc' },
-  limit: 10,
-  offset: 0,
+  return await userRef.getSnapshot()
 })
 ```
 
-### Checking existence
-
-```typescript
-const exists = await orm.exists(User, {
-  where: { email: 'john@example.com' },
-})
-```
-
-### Deleting records
-
-```typescript
-const deleted = await orm.delete(User, {
-  where: { active: false },
-}) // number of deleted rows
-```
-
-`where` is required; an empty `{}` deletes every row.
-
-## Ref
-
-A `Ref<T>` is a reference to a single entity row. It supports `getSnapshot`, `update`, and `remove`:
-
-```typescript
-const userRef = await orm.findOne(User, { where: { id: '...' } })
-
-const user = await userRef.getSnapshot()   // returns the full entity
-await userRef.update({ name: 'Jane' })     // partial update
-await userRef.remove()                     // delete
-```
-
-## RefCollection
-
-A `RefCollection<T>` is a collection of entity references returned by `find` or batch `create`:
-
-```typescript
-const usersRef = await orm.find(User, { where: { active: true } })
-
-const users = usersRef.toArray()            // Ref<User>[]
-usersRef.forEach(ref => { /* ... */ })
-await usersRef.getSnapshots()               // (User | null)[] in one activity
-usersRef.filter(ref => { /* ... */ })
-usersRef.at(0)                              // Ref<User> | undefined
-```
-
-## Relations
-
-`@ManyToOne` owns the relation and stores the related row in a column; `@OneToMany` reads it back from the other table. The to-one side is a `Ref<T>`, the many side a lazy `MapCollection<T>`:
-
-```typescript
-@Entity({ tableName: 'users' })
-class User {
-  @OneToMany(() => Post, post => post.author)
-  public posts!: MapCollection<Post>
-}
-
-@Entity({ tableName: 'posts' })
-class Post {
-  @ManyToOne(() => User)
-  public author!: Ref<User>
-}
-
-await orm.create(Post, { title: 'Hello', author: userRef })
-
-const aliceRef = await orm.findOne(User, { where: { name: 'Alice' } })
-
-const user = await aliceRef!.getSnapshot({
-  populate: ['posts'],          // read in the same activity
-})
-
-await user!.posts.map(post => post.title)
-
-const posts = await aliceRef!.load('posts') // MapCollection<Post>, read when used
-```
-
-See [docs/relations.md](./docs/relations.md).
-
-## Query Operators
-
-The `where` clause supports the following operators:
-
-```typescript
-await orm.find(User, {
-  where: {
-    name: 'John',                    // $eq (implicit)
-    active: { $ne: false },          // not equal
-    email: { $like: '%@example%' },  // LIKE
-    age: { $gte: 18, $lt: 65 },     // range
-  },
-})
-```
-
-Available operators: `$eq`, `$ne`, `$in`, `$nin`, `$not`, `$gt`, `$gte`, `$lt`, `$lte`, `$like`, `$ilike`, `$and`, `$or`.
-
-## Activities
-
-The package includes the following activities (used internally by `ORM` and `Ref`):
+`environments` comes from `EnvDesign` in `src/constants/environments.ts`, with
+`DATABASE_URL` declared as `{ type: Secret }`.
 
-- `ORMCreateActivity` -- creates one or more rows
-- `ORMFindActivity` -- finds multiple rows
-- `ORMFindOneActivity` -- finds a single row
-- `ORMGetSnapshotActivity` -- retrieves full entity data from a ref (no longer used by `Ref.getSnapshot`)
-- `ORMLoadActivity` -- backs `getSnapshot` / `getSnapshots`: retrieves rows with their relations and `populate` in one activity
-- `ORMLoadRelationActivity` -- follows a to-one relation from one or more refs, returning refs
-- `ORMUpdateActivity` -- updates a row
-- `ORMUpsertActivity` -- inserts or updates rows by `conflictOn` (via `ORMClaim.upsert`)
-- `ORMRemoveActivity` -- removes a row
-- `ORMDeleteActivity` -- deletes every row matching a `where`
+## Documentation
 
-All activities extend `SyncActivity` and use `ORMClaim` internally.
+https://tech4humans-brasil.github.io/framework/orm/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/orm",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "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",
@@ -36,7 +36,7 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },