@t4h.framework/orm 0.3.0 → 0.5.0

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

@@ -0,0 +1,339 @@
+---
+name: framework-orm
+description: >-
+  Guides correct use of @t4h.framework/orm in T4H Framework workflows: entity
+  decorators (@Entity, @Property, @Index), the ORM model (create, find, findOne,
+  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
+  workflows with TestWorkflowEnvironment, or working in packages/orm.
+---
+
+# @t4h.framework/orm
+
+ORM activities, claim, and models for database operations within workflows. Package path: `framework/packages/orm`. Peer dependency: `@t4h.framework/core`.
+
+Import from `src/orm.ts` only — do not reference unexported modules:
+
+```typescript
+import {
+  Entity, Property, Index, ORM, Ref, RefCollection,
+  ORMClaim, ConstraintError,
+  ORMCreateActivity, ORMFindActivity, ORMFindOneActivity,
+  ORMGetSnapshotActivity, ORMUpdateActivity, ORMRemoveActivity,
+  getEntityMetadata, getEntityTableName, getEntityProperties,
+  type EntityInsertData, type EntityPartialData, type FindWhere,
+  type SerializableCreateInput, type SerializableFindInput,
+  type SerializableGetSnapshotInput, type SerializableUpdateInput,
+  type SerializableRemoveInput,
+} 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
+
+```typescript
+@Entity({ tableName: 'users' })
+class User {
+  @Property({ type: 'string' })
+  public name!: string
+
+  @Property({ type: 'string' })
+  public email!: string
+
+  @Property({ type: 'boolean', default: true })
+  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).
+
+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.
+
+```typescript
+const orm = new ORM({
+  connectionString: 'postgresql://localhost:5432/mydb',
+  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.
+
+### 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)
+```
+
+`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 } }],
+  },
+})
+```
+
+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` 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
+
+```typescript
+import { ConstraintError, ORM } from '@t4h.framework/orm'
+
+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'
+  }
+}
+```
+
+Constraint checks run **before** activities are invoked — failed creates/updates never reach `ORMClaim`.
+
+---
+
+## ORMClaim (runtime dependency)
+
+Runtime must register a concrete implementation:
+
+```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>
+}
+```
+
+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`.
+
+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` |
+
+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: '...', 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`, `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' }))
+
+const env = TestWorkflowEnvironment.create({ now: 0 })
+
+await env.execute(workflow, input, {
+  claims: [mockClaim(ORMClaim, { create: mockCreate, findOne: mockFindOne })],
+})
+```
+
+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.
+
+See also: `packages/orm/README.md`; **framework-workflow-testing** for the test harness.

package/README.md

@@ -64,6 +64,60 @@ class User {
 })
 ```
 
+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` 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
+4. `assertUniqueConstraint` — no duplicates in the batch, then no conflicting row in storage via `orm.exists`
+
+**Update** (partial patch only):
+
+1. Defaults only for keys present in the patch
+2. Same asserts, scoped to patch keys
+3. Unique checks skip values unchanged vs `getSnapshot()` (same row keeps its current unique value)
+
+### 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`).

package/dist/activities/ORMGetSnapshotActivity.d.ts

@@ -3,11 +3,11 @@ import type { SerializableGetSnapshotInput, SerializableRowRef, SerializedRow }
 declare const CLAIMS_KEY: unique symbol;
 export declare class ORMGetSnapshotActivity extends SyncActivity<[
     input: SerializableGetSnapshotInput<SerializableRowRef>
-], SerializableGetSnapshotInput<SerializableRowRef>, SerializedRow, SerializedRow> {
+], SerializableGetSnapshotInput<SerializableRowRef>, SerializedRow | null, SerializedRow | null> {
     private readonly [CLAIMS_KEY];
     toInput(input: SerializableGetSnapshotInput<SerializableRowRef>): SerializableGetSnapshotInput<SerializableRowRef>;
-    run(input: SerializableGetSnapshotInput<SerializableRowRef>): SerializedRow | Promise<SerializedRow>;
-    toOutput(output: SerializedRow): SerializedRow;
+    run(input: SerializableGetSnapshotInput<SerializableRowRef>): SerializedRow | Promise<SerializedRow | null> | null;
+    toOutput(output: SerializedRow | null): SerializedRow | null;
 }
 export {};
 //# sourceMappingURL=ORMGetSnapshotActivity.d.ts.map

package/dist/activities/ORMGetSnapshotActivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ORMGetSnapshotActivity.d.ts","sourceRoot":"","sources":["../../src/activities/ORMGetSnapshotActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAS,MAAM,qBAAqB,CAAA;AAGzD,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,aAAa,EACd,MAAM,mBAAmB,CAAA;AAE1B,QAAA,MAAM,UAAU,eAA6C,CAAA;AAE7D,qBAAa,sBAAuB,SAAQ,YAAY,CACtD;IAAC,KAAK,EAAE,4BAA4B,CAAC,kBAAkB,CAAC;CAAC,EACzD,4BAA4B,CAAC,kBAAkB,CAAC,EAChD,aAAa,EACb,aAAa,CACd;IACC,OAAO,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAE3B;IAEK,OAAO,CACZ,KAAK,EAAE,4BAA4B,CAAC,kBAAkB,CAAC,GACtD,4BAA4B,CAAC,kBAAkB,CAAC;IAI5C,GAAG,CAAC,KAAK,EAAE,4BAA4B,CAAC,kBAAkB,CAAC;IAI3D,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAGtD"}
+{"version":3,"file":"ORMGetSnapshotActivity.d.ts","sourceRoot":"","sources":["../../src/activities/ORMGetSnapshotActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAS,MAAM,qBAAqB,CAAA;AAGzD,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,aAAa,EACd,MAAM,mBAAmB,CAAA;AAE1B,QAAA,MAAM,UAAU,eAA6C,CAAA;AAE7D,qBAAa,sBAAuB,SAAQ,YAAY,CACtD;IAAC,KAAK,EAAE,4BAA4B,CAAC,kBAAkB,CAAC;CAAC,EACzD,4BAA4B,CAAC,kBAAkB,CAAC,EAChD,aAAa,GAAG,IAAI,EACpB,aAAa,GAAG,IAAI,CACrB;IACC,OAAO,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAE3B;IAEK,OAAO,CACZ,KAAK,EAAE,4BAA4B,CAAC,kBAAkB,CAAC,GACtD,4BAA4B,CAAC,kBAAkB,CAAC;IAI5C,GAAG,CAAC,KAAK,EAAE,4BAA4B,CAAC,kBAAkB,CAAC;IAI3D,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI;CAGpE"}

package/dist/activities/ORMGetSnapshotActivity.js.map

@@ -1 +1 @@
-{"version":3,"file":"ORMGetSnapshotActivity.js","sourceRoot":"","sources":["../../src/activities/ORMGetSnapshotActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAOhD,MAAM,UAAU,GAAG,MAAM,CAAC,kCAAkC,CAAC,CAAA;AAE7D,MAAM,OAAO,sBAAuB,SAAQ,YAK3C;IACkB,CAAC,UAAU,CAAC,GAAG,IAAI,KAAK,CAAC;QACxC,GAAG,EAAE,QAAQ;KACd,CAAC,CAAA;IAEK,OAAO,CACZ,KAAuD;QAEvD,OAAO,KAAK,CAAA;IACd,CAAC;IAEM,GAAG,CAAC,KAAuD;QAChE,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;IAChD,CAAC;IAEM,QAAQ,CAAC,MAAqB;QACnC,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}
+{"version":3,"file":"ORMGetSnapshotActivity.js","sourceRoot":"","sources":["../../src/activities/ORMGetSnapshotActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAOhD,MAAM,UAAU,GAAG,MAAM,CAAC,kCAAkC,CAAC,CAAA;AAE7D,MAAM,OAAO,sBAAuB,SAAQ,YAK3C;IACkB,CAAC,UAAU,CAAC,GAAG,IAAI,KAAK,CAAC;QACxC,GAAG,EAAE,QAAQ;KACd,CAAC,CAAA;IAEK,OAAO,CACZ,KAAuD;QAEvD,OAAO,KAAK,CAAA;IACd,CAAC;IAEM,GAAG,CAAC,KAAuD;QAChE,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;IAChD,CAAC;IAEM,QAAQ,CAAC,MAA4B;QAC1C,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/dist/claims/ORMClaim.d.ts

@@ -2,7 +2,7 @@ import type { SerializableCreateInput, SerializableFindInput, SerializableGetSna
 export declare 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 | Promise<SerializedRow>;
+    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>;
 }

package/dist/claims/ORMClaim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ORMClaim.d.ts","sourceRoot":"","sources":["../../src/claims/ORMClaim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,aAAa,EACd,MAAM,mBAAmB,CAAA;AAE1B,8BAAsB,QAAQ,CAAC,CAAC,SAAS,kBAAkB;aACzC,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;aAEtD,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;aAE1D,WAAW,CACzB,KAAK,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACrC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;aAEzB,MAAM,CACpB,KAAK,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAChC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;aAEP,MAAM,CACpB,KAAK,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAChC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CACxB"}
+{"version":3,"file":"ORMClaim.d.ts","sourceRoot":"","sources":["../../src/claims/ORMClaim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,aAAa,EACd,MAAM,mBAAmB,CAAA;AAE1B,8BAAsB,QAAQ,CAAC,CAAC,SAAS,kBAAkB;aACzC,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;aAEtD,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;aAE1D,WAAW,CACzB,KAAK,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACrC,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;aAEvC,MAAM,CACpB,KAAK,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAChC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;aAEP,MAAM,CACpB,KAAK,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAChC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CACxB"}

package/dist/constraints/__tests__/create-entity-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { EntityMetadata, PropertyMetadata } from '../../decorators/metadata.js';
+export declare function createEntityMetadata(properties: Record<string, Omit<PropertyMetadata, 'name'>>): EntityMetadata;
+//# sourceMappingURL=create-entity-metadata.d.ts.map

package/dist/constraints/__tests__/create-entity-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-entity-metadata.d.ts","sourceRoot":"","sources":["../../../src/constraints/__tests__/create-entity-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,8BAA8B,CAAA;AAErC,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,GACzD,cAAc,CAUhB"}

package/dist/constraints/__tests__/create-entity-metadata.js

@@ -0,0 +1,10 @@
+export function createEntityMetadata(properties) {
+    return {
+        indexes: [],
+        properties: new Map(Object.entries(properties).map(([name, meta]) => [
+            name,
+            { name, indexes: [], ...meta },
+        ])),
+    };
+}
+//# sourceMappingURL=create-entity-metadata.js.map

package/dist/constraints/__tests__/create-entity-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-entity-metadata.js","sourceRoot":"","sources":["../../../src/constraints/__tests__/create-entity-metadata.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,oBAAoB,CAClC,UAA0D;IAE1D,OAAO;QACL,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,IAAI,GAAG,CACjB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;YAC/C,IAAI;YACJ,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE;SAC/B,CAAC,CACH;KACF,CAAA;AACH,CAAC"}

package/dist/constraints/apply-default-properties.d.ts

@@ -0,0 +1,7 @@
+import type { EntityMetadata, SerializedRow } from '../orm.js';
+export declare function applyDefaultProperties(rows: SerializedRow[] | SerializedRow, entity: EntityMetadata, keys?: string[]): {
+    [x: string]: import("@t4h.framework/core").Serializable;
+} | {
+    [x: string]: import("@t4h.framework/core").Serializable;
+}[];
+//# sourceMappingURL=apply-default-properties.d.ts.map

package/dist/constraints/apply-default-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-default-properties.d.ts","sourceRoot":"","sources":["../../src/constraints/apply-default-properties.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAmB9D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,EAAE,GAAG,aAAa,EACrC,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EAAE,MAAM,EAAE;;;;IAMhB"}

package/dist/constraints/apply-default-properties.js

@@ -0,0 +1,16 @@
+function applyDefaultPropertiesToRow(raw, entity, keys) {
+    const row = { ...raw };
+    for (const [name, meta] of entity.properties.entries()) {
+        if (keys && !keys.includes(name))
+            continue;
+        if (row[name] === undefined && meta.default !== undefined)
+            row[name] = meta.default;
+    }
+    return row;
+}
+export function applyDefaultProperties(rows, entity, keys) {
+    if (Array.isArray(rows))
+        return rows.map(raw => applyDefaultPropertiesToRow(raw, entity, keys));
+    return applyDefaultPropertiesToRow(rows, entity, keys);
+}
+//# sourceMappingURL=apply-default-properties.js.map

package/dist/constraints/apply-default-properties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-default-properties.js","sourceRoot":"","sources":["../../src/constraints/apply-default-properties.ts"],"names":[],"mappings":"AAEA,SAAS,2BAA2B,CAClC,GAAkB,EAClB,MAAsB,EACtB,IAAe;IAEf,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,EAAE,CAAA;IAEtB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAQ;QAE1C,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YACvD,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAA;IAC5B,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,IAAqC,EACrC,MAAsB,EACtB,IAAe;IAEf,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IAExE,OAAO,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;AACxD,CAAC"}

package/dist/constraints/assert-constraints.d.ts

@@ -0,0 +1,7 @@
+import { type EntityConstructor, type SerializedRow } from '../orm.js';
+interface AssertConstraintsOptions {
+    keys?: string[];
+}
+export declare function assertConstraints<T>(entity: EntityConstructor<T>, rows: SerializedRow[], options?: AssertConstraintsOptions): Promise<void>;
+export {};
+//# sourceMappingURL=assert-constraints.d.ts.map

package/dist/constraints/assert-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-constraints.d.ts","sourceRoot":"","sources":["../../src/constraints/assert-constraints.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,WAAW,CAAA;AAIlB,UAAU,wBAAwB;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC5B,IAAI,EAAE,aAAa,EAAE,EACrB,OAAO,CAAC,EAAE,wBAAwB,iBAWnC"}

package/dist/constraints/assert-constraints.js

@@ -0,0 +1,13 @@
+import { getEntityMetadata, } from '../orm.js';
+import { assertNonNullablePropertyConstraint } from './assert-non-nullable-property-constraint.js';
+import { assertPropertyTypeConstraint } from './assert-property-type-constraint.js';
+export async function assertConstraints(entity, rows, options) {
+    const entityMetadata = getEntityMetadata(entity);
+    assertPropertyTypeConstraint(rows, entityMetadata, {
+        keys: options?.keys,
+    });
+    assertNonNullablePropertyConstraint(rows, entityMetadata, {
+        keys: options?.keys,
+    });
+}
+//# sourceMappingURL=assert-constraints.js.map

package/dist/constraints/assert-constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-constraints.js","sourceRoot":"","sources":["../../src/constraints/assert-constraints.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAGlB,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,mCAAmC,EAAE,MAAM,8CAA8C,CAAA;AAClG,OAAO,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAA;AAMnF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAA4B,EAC5B,IAAqB,EACrB,OAAkC;IAElC,MAAM,cAAc,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;IAEhD,4BAA4B,CAAC,IAAI,EAAE,cAAc,EAAE;QACjD,IAAI,EAAE,OAAO,EAAE,IAAI;KACpB,CAAC,CAAA;IAEF,mCAAmC,CAAC,IAAI,EAAE,cAAc,EAAE;QACxD,IAAI,EAAE,OAAO,EAAE,IAAI;KACpB,CAAC,CAAA;AACJ,CAAC"}

package/dist/constraints/assert-non-nullable-property-constraint.d.ts

@@ -0,0 +1,7 @@
+import type { EntityMetadata, SerializedRow } from '../orm.js';
+interface AssertNonNullablePropertyConstraintOptions {
+    keys?: string[];
+}
+export declare function assertNonNullablePropertyConstraint(rows: SerializedRow[], entity: EntityMetadata, options?: AssertNonNullablePropertyConstraintOptions): void;
+export {};
+//# sourceMappingURL=assert-non-nullable-property-constraint.d.ts.map

package/dist/constraints/assert-non-nullable-property-constraint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-non-nullable-property-constraint.d.ts","sourceRoot":"","sources":["../../src/constraints/assert-non-nullable-property-constraint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9D,UAAU,0CAA0C;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,aAAa,EAAE,EACrB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,0CAA0C,QAYrD"}

package/dist/constraints/assert-non-nullable-property-constraint.js

@@ -0,0 +1,14 @@
+import { ConstraintError } from '../errors/ConstraintError.js';
+export function assertNonNullablePropertyConstraint(rows, entity, options) {
+    rows.forEach(row => {
+        for (const [name, meta] of entity.properties.entries()) {
+            if (options?.keys && !options.keys.includes(name))
+                continue;
+            if (meta.nullable)
+                continue;
+            if (row[name] === null || row[name] === undefined)
+                throw new ConstraintError(`Property "${name}" is required`);
+        }
+    });
+}
+//# sourceMappingURL=assert-non-nullable-property-constraint.js.map

package/dist/constraints/assert-non-nullable-property-constraint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-non-nullable-property-constraint.js","sourceRoot":"","sources":["../../src/constraints/assert-non-nullable-property-constraint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAO9D,MAAM,UAAU,mCAAmC,CACjD,IAAqB,EACrB,MAAsB,EACtB,OAAoD;IAEpD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;QACjB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;YACvD,IAAI,OAAO,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAE3D,IAAI,IAAI,CAAC,QAAQ;gBAAE,SAAQ;YAE3B,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS;gBAC/C,MAAM,IAAI,eAAe,CAAC,aAAa,IAAI,eAAe,CAAC,CAAA;QAC/D,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/constraints/assert-property-type-constraint.d.ts

@@ -0,0 +1,7 @@
+import type { EntityMetadata, SerializedRow } from '../orm.js';
+interface AssertPropertyTypeConstraintOptions {
+    keys?: string[];
+}
+export declare function assertPropertyTypeConstraint(rows: SerializedRow[], entity: EntityMetadata, options?: AssertPropertyTypeConstraintOptions): void;
+export {};
+//# sourceMappingURL=assert-property-type-constraint.d.ts.map

package/dist/constraints/assert-property-type-constraint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-property-type-constraint.d.ts","sourceRoot":"","sources":["../../src/constraints/assert-property-type-constraint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAgB9D,UAAU,mCAAmC;IAC3C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,aAAa,EAAE,EACrB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,mCAAmC,QAyB9C"}

package/dist/constraints/assert-property-type-constraint.js

@@ -0,0 +1,30 @@
+import { ConstraintError } from '../errors/ConstraintError.js';
+const UUID_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const PROPERTY_TYPE = {
+    string: (value) => typeof value === 'string',
+    uuid: (value) => typeof value === 'string' && UUID_REGEX.test(value),
+    number: (value) => typeof value === 'number' && !Number.isNaN(value),
+    boolean: (value) => typeof value === 'boolean',
+    array: (value) => Array.isArray(value),
+    date: (value) => value instanceof Date || typeof value === 'string',
+    object: (value) => typeof value === 'object' && value !== null && !Array.isArray(value),
+};
+export function assertPropertyTypeConstraint(rows, entity, options) {
+    rows.forEach(row => {
+        for (const [name, meta] of entity.properties.entries()) {
+            if (options?.keys && !options.keys.includes(name))
+                continue;
+            const value = row[name];
+            if (!meta.type)
+                continue;
+            if (value === undefined || value === null)
+                continue;
+            const validator = PROPERTY_TYPE[meta.type];
+            if (!validator)
+                throw new ConstraintError(`Property "${name}" has unsupported type "${meta.type}"`);
+            if (!validator(value))
+                throw new ConstraintError(`Property "${name}" must be of type ${meta.type}`);
+        }
+    });
+}
+//# sourceMappingURL=assert-property-type-constraint.js.map

package/dist/constraints/assert-property-type-constraint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-property-type-constraint.js","sourceRoot":"","sources":["../../src/constraints/assert-property-type-constraint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAG9D,MAAM,UAAU,GACd,+EAA+E,CAAA;AAEjF,MAAM,aAAa,GAAG;IACpB,MAAM,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ;IACrD,IAAI,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;IAC7E,MAAM,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;IAC7E,OAAO,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,SAAS;IACvD,KAAK,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;IAC/C,IAAI,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,YAAY,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;IAC5E,MAAM,EAAE,CAAC,KAAc,EAAE,EAAE,CACzB,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;CACvE,CAAA;AAMD,MAAM,UAAU,4BAA4B,CAC1C,IAAqB,EACrB,MAAsB,EACtB,OAA6C;IAE7C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;QACjB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;YACvD,IAAI,OAAO,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAE3D,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;YAEvB,IAAI,CAAC,IAAI,CAAC,IAAI;gBAAE,SAAQ;YAExB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;gBAAE,SAAQ;YAEnD,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAkC,CAAC,CAAA;YAExE,IAAI,CAAC,SAAS;gBACZ,MAAM,IAAI,eAAe,CACvB,aAAa,IAAI,2BAA2B,IAAI,CAAC,IAAI,GAAG,CACzD,CAAA;YAEH,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;gBACnB,MAAM,IAAI,eAAe,CACvB,aAAa,IAAI,qBAAqB,IAAI,CAAC,IAAI,EAAE,CAClD,CAAA;QACL,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/constraints/assert-unique-constraint.d.ts

@@ -0,0 +1,11 @@
+import type { Serializable } from '@t4h.framework/core';
+import type { EntityMetadata, SerializedRow } from '../orm.js';
+import type { FindWhere } from '../typings/FindWhere.js';
+interface AssertUniqueConstraintOptions<T> {
+    keys?: string[];
+    validator: (where: FindWhere<T>) => Promise<unknown>;
+    isUnchanged?: (name: string, value: Serializable) => boolean;
+}
+export declare function assertUniqueConstraint<T>(rows: SerializedRow[], entity: EntityMetadata, options: AssertUniqueConstraintOptions<T>): Promise<void>;
+export {};
+//# sourceMappingURL=assert-unique-constraint.d.ts.map

package/dist/constraints/assert-unique-constraint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-unique-constraint.d.ts","sourceRoot":"","sources":["../../src/constraints/assert-unique-constraint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGvD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD,UAAU,6BAA6B,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACpD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAA;CAC7D;AA6BD,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,aAAa,EAAE,EACrB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,iBA6B1C"}