@marianmeres/collection-types 2.2.0 → 2.4.0

package/AGENTS.md

@@ -15,6 +15,7 @@ entry: "./src/mod.ts"
 ## Purpose
 
 Type definitions and schema utilities for the collection management system:
+
 - Core types: Model, Collection, Relation
 - Branded types: UUID, ISODateString, LtreePath
 - Domain types: Account, Product, Order, Customer, Session, etc.
@@ -23,17 +24,17 @@ Type definitions and schema utilities for the collection management system:
 
 ## Quick Reference
 
-| Task | File | Key Export |
-|------|------|------------|
-| Branded types | `src/utils.ts` | `UUID`, `ISODateString`, `LtreePath` |
-| Model types | `src/model.ts` | `Model<T>`, `ModelDTOIn`, `ModelDTOOut` |
-| Collection types | `src/collection.ts` | `Collection`, `CollectionDTOIn` |
-| Relation types | `src/relation.ts` | `Relation`, `RelationType` |
-| Schema types | `src/schema.ts` | `PropertyDefinition`, `JsonSchema` |
-| Schema builder | `src/schema-builder.ts` | `createObjectSchema<T>()` |
-| API types | `src/api.ts` | `ApiResponse`, `PaginatedResponse` |
-| Asset types | `src/asset.ts` | `AssetData`, `AssetVariant` |
-| Navigation types | `src/navigation.ts` | `NavItem`, `UnifiedNavigation` |
+| Task             | File                    | Key Export                              |
+| ---------------- | ----------------------- | --------------------------------------- |
+| Branded types    | `src/utils.ts`          | `UUID`, `ISODateString`, `LtreePath`    |
+| Model types      | `src/model.ts`          | `Model<T>`, `ModelDTOIn`, `ModelDTOOut` |
+| Collection types | `src/collection.ts`     | `Collection`, `CollectionDTOIn`         |
+| Relation types   | `src/relation.ts`       | `Relation`, `RelationType`              |
+| Schema types     | `src/schema.ts`         | `PropertyDefinition`, `JsonSchema`      |
+| Schema builder   | `src/schema-builder.ts` | `createObjectSchema<T>()`               |
+| API types        | `src/api.ts`            | `ApiResponse`, `PaginatedResponse`      |
+| Asset types      | `src/asset.ts`          | `AssetData`, `AssetVariant`             |
+| Navigation types | `src/navigation.ts`     | `NavItem`, `UnifiedNavigation`          |
 
 ## File Map
 
@@ -74,32 +75,54 @@ src/
 
 ```typescript
 // Branded types
-export type { UUID, ISODateString, LtreePath, MaybeLocalized } from "./utils.ts";
-export type { JsonPrimitive, JsonObject, JsonArray, JsonValue, UserData } from "./utils.ts";
+export type { ISODateString, LtreePath, MaybeLocalized, UUID } from "./utils.ts";
+export type {
+	JsonArray,
+	JsonObject,
+	JsonPrimitive,
+	JsonValue,
+	UserData,
+} from "./utils.ts";
 
 // Core entities
-export type { Model, ModelDTOIn, ModelDTOOut, ModelDbRow, ModelUpsertData } from "./model.ts";
-export type { Collection, CollectionDTOIn, CollectionDTOOut, CollectionDbRow } from "./collection.ts";
-export type { Relation, RelationType, RelationDTOIn, RelationTypeDTOIn } from "./relation.ts";
+export type {
+	Model,
+	ModelDbRow,
+	ModelDTOIn,
+	ModelDTOOut,
+	ModelUpsertData,
+} from "./model.ts";
+export type {
+	Collection,
+	CollectionDbRow,
+	CollectionDTOIn,
+	CollectionDTOOut,
+} from "./collection.ts";
+export type {
+	Relation,
+	RelationDTOIn,
+	RelationType,
+	RelationTypeDTOIn,
+} from "./relation.ts";
 
 // Schema
-export type { PropertyDefinition, JsonSchema, HtmlSpec } from "./schema.ts";
-export type { ObjectSchema, ExtendedSchema } from "./schema-builder.ts";
-export { createObjectSchema } from "./schema-builder.ts";  // Runtime function
+export type { HtmlSpec, JsonSchema, PropertyDefinition } from "./schema.ts";
+export type { ExtendedSchema, ObjectSchema } from "./schema-builder.ts";
+export { createObjectSchema } from "./schema-builder.ts"; // Runtime function
 
 // API
-export type { ApiResponse, PaginatedResponse, ApiMeta } from "./api.ts";
+export type { ApiMeta, ApiResponse, PaginatedResponse } from "./api.ts";
 
 // Assets
 export type { AssetData, AssetVariant } from "./asset.ts";
 
 // Domain types
 export type { AccountData, AccountSession } from "./account.ts";
-export type { ProductData, CategoryData } from "./product.ts";
+export type { CategoryData, ProductData } from "./product.ts";
 export type { CustomerData } from "./customer.ts";
 export type { OrderData, OrderItemData } from "./order.ts";
 export type { PaymentData } from "./payment.ts";
-export type { SessionData, CartItem } from "./session.ts";
+export type { CartItem, SessionData } from "./session.ts";
 export type { TemplateData } from "./template.ts";
 export type { EmailData } from "./email.ts";
 
@@ -115,10 +138,10 @@ export type { JoyConfig } from "./joy-config.ts";
 ### Branded Types
 
 ```typescript
-type UUID = string;           // UUID string
-type ISODateString = string;  // ISO 8601 date string
-type LtreePath = string;      // PostgreSQL ltree path
-type MaybeLocalized<T> = T | Record<string, T>;  // i18n support
+type UUID = string; // UUID string
+type ISODateString = string; // ISO 8601 date string
+type LtreePath = string; // PostgreSQL ltree path
+type MaybeLocalized<T> = T | Record<string, T>; // i18n support
 ```
 
 ### Model Layer Types
@@ -126,39 +149,45 @@ type MaybeLocalized<T> = T | Record<string, T>;  // i18n support
 ```typescript
 // Input (user-provided)
 interface ModelDTOIn {
-  type?: string;
-  parent_id?: UUID | null;
-  path?: LtreePath | null;
-  folder?: string | null;
-  tags?: string[];
-  data?: UserData;
-  meta?: UserData;
-  is_unlisted?: boolean;
-  is_deletable?: boolean;
-  is_readonly?: boolean;
-  is_starred?: boolean;
-  is_enabled?: boolean;
-  red?, orange?, yellow?, green?, blue?, purple?, gray?: boolean;
+	type?: string;
+	parent_id?: UUID | null;
+	path?: LtreePath | null;
+	folder?: string | null;
+	tags?: string[];
+	data?: UserData;
+	meta?: UserData;
+	is_unlisted?: boolean;
+	is_deletable?: boolean;
+	is_readonly?: boolean;
+	is_starred?: boolean;
+	is_enabled?: boolean;
+	red?;
+	orange?;
+	yellow?;
+	green?;
+	blue?;
+	purple?;
+	gray?: boolean;
 }
 
 // Output (+ server fields)
 interface ModelDTOOut extends ModelDTOIn {
-  model_id: UUID;
-  collection_id: UUID;
-  type: string;
-  depth: number;
-  _label?: MaybeLocalized<string> | null;
-  _hierarchy_label?: string | null;
-  _created_at: ISODateString;
-  _updated_at: ISODateString;
+	model_id: UUID;
+	collection_id: UUID;
+	type: string;
+	depth: number;
+	_label?: MaybeLocalized<string> | null;
+	_hierarchy_label?: string | null;
+	_created_at: ISODateString;
+	_updated_at: ISODateString;
 }
 
 // Database (+ internal fields)
 interface ModelDbRow extends ModelDTOOut {
-  __is_rest_disabled: boolean;
-  __searchable: Record<string, unknown>;
-  __searchable2: string;
-  __hierarchy_path: LtreePath | null;
+	__is_rest_disabled: boolean;
+	__searchable: Record<string, unknown>;
+	__searchable2: string;
+	__hierarchy_path: LtreePath | null;
 }
 
 // Generic typed model
@@ -169,13 +198,13 @@ type Model<TData extends UserData = UserData> = ModelDbRow & { data: TData };
 
 ```typescript
 interface ObjectSchema<T> {
-  type: "object";
-  required?: (keyof T)[];
-  properties: { [K in keyof T]?: PropertyDefinition };
-  additionalProperties?: boolean;
-  _title?: MaybeLocalized<string>;
-  _description?: MaybeLocalized<string>;
-  _extra_form_fields?: Record<string, PropertyDefinition>;
+	type: "object";
+	required?: (keyof T)[];
+	properties: { [K in keyof T]?: PropertyDefinition };
+	additionalProperties?: boolean;
+	_title?: MaybeLocalized<string>;
+	_description?: MaybeLocalized<string>;
+	_extra_form_fields?: Record<string, PropertyDefinition>;
 }
 
 // Type-safe schema creation
@@ -183,8 +212,8 @@ function createObjectSchema<T>(schema: ObjectSchema<T>): ObjectSchema<T>;
 
 // Inheritance pattern
 type ExtendedSchema = {
-  __extends: string;
-  properties?: Record<string, PropertyDefinition>;
+	__extends: string;
+	properties?: Record<string, PropertyDefinition>;
 };
 ```
 
@@ -213,26 +242,26 @@ Field Prefixes:
 import { createObjectSchema, type Model } from "@marianmeres/collection-types";
 
 interface ProductData {
-  name: string;
-  price: number;
-  sku: string;
+	name: string;
+	price: number;
+	sku: string;
 }
 
 // TypeScript validates property keys match interface
 const productSchema = createObjectSchema<ProductData>({
-  type: "object",
-  required: ["name", "price"],
-  properties: {
-    name: { type: "string", _label_source: true },
-    price: { type: "number" },
-    sku: { type: "string", _unique: true }
-  }
+	type: "object",
+	required: ["name", "price"],
+	properties: {
+		name: { type: "string", _label_source: true },
+		price: { type: "number" },
+		sku: { type: "string", _unique: true },
+	},
 });
 
 // Typed model usage
 type Product = Model<ProductData>;
 const product: Product = await service.findOne(id);
-console.log(product.data.price);  // TypeScript knows this is number
+console.log(product.data.price); // TypeScript knows this is number
 ```
 
 ### Schema Inheritance
@@ -242,23 +271,27 @@ import type { ExtendedSchema } from "@marianmeres/collection-types";
 
 // Base schema
 const baseSchema = createObjectSchema<{ name: string }>({
-  type: "object",
-  properties: { name: { type: "string" } }
+	type: "object",
+	properties: { name: { type: "string" } },
 });
 
 // Extended schema
 const featuredSchema: ExtendedSchema = {
-  __extends: "default",
-  properties: {
-    featured_until: { type: "string", format: "date" }
-  }
+	__extends: "default",
+	properties: {
+		featured_until: { type: "string", format: "date" },
+	},
 };
 ```
 
 ### API Response Types
 
 ```typescript
-import type { ApiResponse, PaginatedResponse, Model } from "@marianmeres/collection-types";
+import type {
+	ApiResponse,
+	Model,
+	PaginatedResponse,
+} from "@marianmeres/collection-types";
 
 // Single item response
 type ProductResponse = ApiResponse<Model<ProductData>>;
@@ -279,6 +312,7 @@ deno task rpm          # Release minor
 ## Dependencies
 
 This is a types-only package with minimal dependencies:
+
 - None (pure TypeScript types)
 
 ## Conventions
@@ -300,7 +334,7 @@ This is a types-only package with minimal dependencies:
 2. **Import style**: Use `import type` for type-only imports to ensure tree-shaking:
    ```typescript
    import type { Model, UUID } from "@marianmeres/collection-types";
-   import { createObjectSchema } from "@marianmeres/collection-types";  // Runtime
+   import { createObjectSchema } from "@marianmeres/collection-types"; // Runtime
    ```
 
 3. **MaybeLocalized**: Fields that support i18n can be either a direct value or a `Record<lang, value>`:

package/README.md

@@ -14,29 +14,26 @@ This package provides:
 
 ```typescript
 import type {
-  Model,
-  Collection,
-  UUID,
-  ProductData,
-  CustomerData,
+	Collection,
+	CustomerData,
+	Model,
+	ProductData,
+	UUID,
 } from "@marianmeres/collection-types";
 
-import {
-  createObjectSchema,
-  type ExtendedSchema,
-} from "@marianmeres/collection-types";
+import { createObjectSchema, type ExtendedSchema } from "@marianmeres/collection-types";
 ```
 
 ## Type Layers
 
 The collection system uses a layered type structure:
 
-| Layer | Interface | Purpose |
-|-------|-----------|---------|
-| Input | `ModelDTOIn` | User-provided fields for create/update |
-| Output | `ModelDTOOut` | Response with server-generated fields |
-| Database | `ModelDbRow` | Full row including internal fields |
-| Typed | `Model<T>` | Generic model with typed `data` field |
+| Layer    | Interface     | Purpose                                |
+| -------- | ------------- | -------------------------------------- |
+| Input    | `ModelDTOIn`  | User-provided fields for create/update |
+| Output   | `ModelDTOOut` | Response with server-generated fields  |
+| Database | `ModelDbRow`  | Full row including internal fields     |
+| Typed    | `Model<T>`    | Generic model with typed `data` field  |
 
 ```typescript
 import type { Model } from "@marianmeres/collection-types";
@@ -50,34 +47,34 @@ type ProductModel = Model<ProductData>;
 
 ### Core Types
 
-| File | Exports |
-|------|---------|
-| `model.ts` | ModelDTOIn, ModelDTOOut, ModelDbRow, Model |
-| `collection.ts` | Collection, CollectionDTOIn, CollectionDTOOut |
-| `relation.ts` | Relation, RelationType |
-| `schema.ts` | PropertyDefinition, SchemaDefinition |
-| `utils.ts` | UUID, LtreePath, ISODateString, MaybeLocalized |
+| File            | Exports                                        |
+| --------------- | ---------------------------------------------- |
+| `model.ts`      | ModelDTOIn, ModelDTOOut, ModelDbRow, Model     |
+| `collection.ts` | Collection, CollectionDTOIn, CollectionDTOOut  |
+| `relation.ts`   | Relation, RelationType                         |
+| `schema.ts`     | PropertyDefinition, SchemaDefinition           |
+| `utils.ts`      | UUID, LtreePath, ISODateString, MaybeLocalized |
 
 ### E-commerce Types
 
-| File | Exports |
-|------|---------|
-| `session.ts` | SessionData, CartData, CartItem |
-| `customer.ts` | CustomerData, AddressData |
-| `order.ts` | OrderData, OrderEventData, OrderLineItem, OrderTotals |
-| `payment.ts` | PaymentData, PaymentIntent, PaymentResult |
+| File          | Exports                                               |
+| ------------- | ----------------------------------------------------- |
+| `session.ts`  | SessionData, CartData, CartItem                       |
+| `customer.ts` | CustomerData, AddressData                             |
+| `order.ts`    | OrderData, OrderEventData, OrderLineItem, OrderTotals |
+| `payment.ts`  | PaymentData, PaymentIntent, PaymentResult             |
 
 ### Stack Domain Types
 
-| File | Exports |
-|------|---------|
-| `account.ts` | AccountData, PasswordData, TokenData |
-| `product.ts` | ProductData, CategoryData |
-| `project.ts` | ConfigData, ConfigDataDefault, ConfigDataRbac |
-| `template.ts` | TemplateData |
-| `email.ts` | EmailData, EmailStatus |
-| `asset.ts` | AssetData, AssetVariant, ModelAsset |
-| `example.ts` | ExampleData, ExampleDataDefault, CommentData |
+| File          | Exports                                       |
+| ------------- | --------------------------------------------- |
+| `account.ts`  | AccountData, PasswordData, TokenData          |
+| `product.ts`  | ProductData, CategoryData                     |
+| `project.ts`  | ConfigData, ConfigDataDefault, ConfigDataRbac |
+| `template.ts` | TemplateData                                  |
+| `email.ts`    | EmailData, EmailStatus                        |
+| `asset.ts`    | AssetData, AssetVariant, ModelAsset           |
+| `example.ts`  | ExampleData, ExampleDataDefault, CommentData  |
 
 ## Type-Safe Schema Definitions
 
@@ -90,28 +87,25 @@ Without type safety, typos in schema property names are not caught:
 ```typescript
 // BAD: TypeScript does NOT catch the typo "namex"
 const schema = {
-  type: "object",
-  properties: {
-    namex: { type: "string" },  // Typo! Should be "name"
-  },
+	type: "object",
+	properties: {
+		namex: { type: "string" }, // Typo! Should be "name"
+	},
 };
 ```
 
 ### The Solution
 
 ```typescript
-import {
-  createObjectSchema,
-  type ProductData,
-} from "@marianmeres/collection-types";
+import { createObjectSchema, type ProductData } from "@marianmeres/collection-types";
 
 // GOOD: TypeScript catches typos!
 const schema = createObjectSchema<ProductData>({
-  type: "object",
-  required: ["name"],
-  properties: {
-    namex: { type: "string" },  // TS Error: 'namex' does not exist
-  },
+	type: "object",
+	required: ["name"],
+	properties: {
+		namex: { type: "string" }, // TS Error: 'namex' does not exist
+	},
 });
 ```
 
@@ -125,17 +119,17 @@ Data interfaces must include:
 
 ```typescript
 export interface ProductData {
-  // Data fields
-  name: string;
-  price?: number;
-  sku?: string;
+	// Data fields
+	name: string;
+	price?: number;
+	sku?: string;
 
-  // UI-only fields (never stored in data)
-  category?: never;
-  images?: never;
+	// UI-only fields (never stored in data)
+	category?: never;
+	images?: never;
 
-  // Index signature for Model<T> compatibility
-  [key: string]: unknown;
+	// Index signature for Model<T> compatibility
+	[key: string]: unknown;
 }
 ```
 
@@ -147,21 +141,21 @@ For schemas using `__extends`, use `ExtendedSchema`:
 import { type ExtendedSchema } from "@marianmeres/collection-types";
 
 const schemas = {
-  default: createObjectSchema<ProductData>({
-    type: "object",
-    required: ["name"],
-    properties: {
-      name: { type: "string" },
-      price: { type: "integer" },
-    },
-  }),
-
-  premium: {
-    __extends: "default",
-    properties: {
-      warranty_years: { type: "integer" },
-    },
-  } as ExtendedSchema,
+	default: createObjectSchema<ProductData>({
+		type: "object",
+		required: ["name"],
+		properties: {
+			name: { type: "string" },
+			price: { type: "integer" },
+		},
+	}),
+
+	premium: {
+		__extends: "default",
+		properties: {
+			warranty_years: { type: "integer" },
+		},
+	} as ExtendedSchema,
 };
 ```
 

package/dist/adapter.d.ts

@@ -18,7 +18,7 @@ export interface DbQueryResult<T = Record<string, unknown>> {
  */
 export interface QueryProvider {
     /** Query provider type */
-    type: "pg" | "sqlite";
+    type: "pg";
     /** Execute a query and return results */
     query(sql: string, params?: unknown[]): Promise<DbQueryResult>;
     /** Execute a query with cursor-style row iteration */

package/dist/asset.d.ts

@@ -2,7 +2,7 @@
  * Asset types for the collection system.
  * Assets are file attachments associated with models.
  */
-import type { UUID, ISODateString } from "./utils.js";
+import type { ISODateString, UUID } from "./utils.js";
 /**
  * Variant of an asset (e.g., thumbnail, preview).
  */

package/dist/collection.d.ts

@@ -2,7 +2,7 @@
  * Collection types for the collection system.
  * Collections are containers for models with schema definitions.
  */
-import type { UUID, ISODateString, LtreePath, UserData } from "./utils.js";
+import type { ISODateString, LtreePath, UserData, UUID } from "./utils.js";
 import type { PropertyDefinition } from "./schema.js";
 /**
  * Defines how ownership (`owner_id`) behaves for a collection.

package/dist/model.d.ts

@@ -2,7 +2,7 @@
  * Model types for the collection system.
  * Defines the structure of model records at different layers (input, output, database).
  */
-import type { UUID, ISODateString, LtreePath, UserData, MaybeLocalized } from "./utils.js";
+import type { ISODateString, LtreePath, MaybeLocalized, UserData, UUID } from "./utils.js";
 /**
  * Input DTO for creating/updating a model.
  * Contains user-provided fields for model creation.

package/dist/navigation.d.ts

@@ -48,6 +48,15 @@ export interface NavConfig {
         label?: MaybeLocalized<string>;
         order?: number;
         icon?: string;
+        /**
+         * Stable, non-localized key that buckets this domain/entity into a
+         * nav group. Defaults to the domain. Set the SAME `groupKey` (and a
+         * matching `group` label) on several entries to merge multiple
+         * domains under one group — e.g. `order` + `invoice` → "Sales".
+         * Must be a plain string (it is used as a Map key), never a
+         * localized object.
+         */
+        groupKey?: string;
         group?: MaybeLocalized<string>;
         groupIcon?: string;
         folder?: string;
@@ -94,8 +103,12 @@ export interface NavItemDef {
  * Area identifiers for the admin SPA.
  * Each area represents a distinct section of the application with its own
  * routing pattern and navigation structure.
+ *
+ * `todo` is a bespoke direct-route area (the `me`/`extra` precedent — NOT in the
+ * client AreaRegistry); it ships as a prebuilt passthrough from
+ * `__joy_nav__.areas.todo`, gated to root only via `requiredPermissions`.
  */
-export type AreaId = "cms" | "custom" | "user" | "extra" | "me";
+export type AreaId = "cms" | "custom" | "user" | "extra" | "me" | "todo";
 /**
  * Base nav item structure shared across all areas.
  * Designed to support hierarchical navigation (groups, pages, tabs).

package/dist/order.d.ts

@@ -53,6 +53,16 @@ export interface DeliveryOptionSnapshot {
 }
 /** Order data field schema */
 export interface OrderData {
+    /**
+     * Public, customer-facing order identifier shown in place of the model UUID
+     * everywhere the customer is involved (checkout confirmation, emails, the
+     * printed order document, account order history). Non-sequential Crockford
+     * base32 (uppercase, length 6), generated and uniqueness-checked at creation,
+     * then FROZEN — never changed on any subsequent update. Mirrors
+     * `InvoiceData.code`. Optional so legacy/admin-created rows that predate the
+     * field still type-check; read paths fall back to `shortOrderRef(model_id)`.
+     */
+    code?: string;
     /** Current order status */
     status: OrderStatus;
     /** Line items (snapshots) */

package/dist/relation.d.ts

@@ -2,7 +2,7 @@
  * Relation types for the collection system.
  * Relations link models across collections with typed relationships.
  */
-import type { UUID, ISODateString, UserData } from "./utils.js";
+import type { ISODateString, UserData, UUID } from "./utils.js";
 /**
  * Input DTO for creating/updating a relation type.
  * A RelationType defines a typed relationship between models from different collections.

package/dist/schema.d.ts

@@ -4,7 +4,7 @@
  */
 import type { MaybeLocalized } from "./utils.js";
 /** HTML field type for UI rendering */
-export type SchemaHtmlType = "text" | "textarea" | "wysiwyg" | "markdown" | "number" | "money" | "boolean" | "checkbox" | "parent" | "object" | "select" | "status" | "multiselect" | "date" | "datetime" | "time" | "color" | "relation" | "asset" | "json" | "code" | "keyvalues" | "password";
+export type SchemaHtmlType = "text" | "textarea" | "wysiwyg" | "markdown" | "number" | "money" | "boolean" | "checkbox" | "parent" | "object" | "select" | "status" | "multiselect" | "date" | "datetime" | "time" | "color" | "relation" | "asset" | "json" | "code" | "keyvalues" | "password" | "user";
 /** Configuration for relation-type fields in schema */
 export interface RelationTypeConfig {
     relation_type: string;
@@ -15,6 +15,12 @@ export interface RelationTypeConfig {
     type?: string;
     /** Allow unknown relations */
     allow_unknown?: boolean;
+    /**
+     * When true (and the relation is multi-value, i.e. `cardinality !== 1`), the
+     * admin UI exposes a manual reorder control. The chosen order is persisted as
+     * the relation `sort_order`. No-op for single-cardinality relations.
+     */
+    ordered?: boolean;
 }
 /** Configuration for asset-type fields in schema */
 export interface AssetTypeConfig {

package/docs/type-catalog.md

@@ -15,163 +15,163 @@ Relation:     RelationDTOIn → RelationDTOOut → RelationDbRow (= Relation)
 
 ## utils.ts — Branded Types & Helpers
 
-| Type | Description |
-|------|-------------|
-| `UUID` | String type for UUIDs |
-| `ISODateString` | String type for ISO 8601 dates |
-| `LtreePath` | String type for PostgreSQL ltree paths |
+| Type                | Description                                   |
+| ------------------- | --------------------------------------------- |
+| `UUID`              | String type for UUIDs                         |
+| `ISODateString`     | String type for ISO 8601 dates                |
+| `LtreePath`         | String type for PostgreSQL ltree paths        |
 | `MaybeLocalized<T>` | `T \| Record<string, T>` for localized values |
-| `JsonPrimitive` | `string \| number \| boolean \| null` |
-| `JsonObject` | `{ [key: string]: JsonValue }` |
-| `JsonArray` | `JsonValue[]` |
-| `JsonValue` | `JsonPrimitive \| JsonObject \| JsonArray` |
-| `UserData` | `Record<string, unknown>` for flexible data |
-| `Brand<T, B>` | Helper for creating branded types |
+| `JsonPrimitive`     | `string \| number \| boolean \| null`         |
+| `JsonObject`        | `{ [key: string]: JsonValue }`                |
+| `JsonArray`         | `JsonValue[]`                                 |
+| `JsonValue`         | `JsonPrimitive \| JsonObject \| JsonArray`    |
+| `UserData`          | `Record<string, unknown>` for flexible data   |
+| `Brand<T, B>`       | Helper for creating branded types             |
 
 ## model.ts — Model Entity Types
 
-| Type | Description |
-|------|-------------|
-| `ModelDTOIn` | Input DTO (type, parent_id, path, folder, tags, data, meta, flags) |
-| `ModelDTOOut` | + model_id, collection_id, depth, _label, _created_at, _updated_at |
-| `ModelDbRow` | + __is_rest_disabled, __searchable, __searchable2, __hierarchy_path |
-| `ModelUpsertData` | + __relations__ for relation upserts |
-| `Model<TData>` | Generic type with typed data field |
+| Type              | Description                                                         |
+| ----------------- | ------------------------------------------------------------------- |
+| `ModelDTOIn`      | Input DTO (type, parent_id, path, folder, tags, data, meta, flags)  |
+| `ModelDTOOut`     | + model_id, collection_id, depth, _label, _created_at, _updated_at  |
+| `ModelDbRow`      | + __is_rest_disabled, __searchable, __searchable2, __hierarchy_path |
+| `ModelUpsertData` | + **relations** for relation upserts                                |
+| `Model<TData>`    | Generic type with typed data field                                  |
 
 ## collection.ts — Collection Container Types
 
-| Type | Description |
-|------|-------------|
-| `FolderDefinition` | Folder config (label, description, color) |
-| `TagDefinition` | Tag config (label, color) |
-| `CollectionDTOIn` | Input DTO (path, cardinality, types, schemas, defaults, folders, tags) |
-| `CollectionDTOOut` | + collection_id, project_id, _created_at, _updated_at |
-| `CollectionDbRow` | + __is_rest_disabled |
-| `Collection` | Alias for CollectionDbRow |
+| Type               | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| `FolderDefinition` | Folder config (label, description, color)                              |
+| `TagDefinition`    | Tag config (label, color)                                              |
+| `CollectionDTOIn`  | Input DTO (path, cardinality, types, schemas, defaults, folders, tags) |
+| `CollectionDTOOut` | + collection_id, project_id, _created_at, _updated_at                  |
+| `CollectionDbRow`  | + __is_rest_disabled                                                   |
+| `Collection`       | Alias for CollectionDbRow                                              |
 
 ## relation.ts — Relationship Types
 
-| Type | Description |
-|------|-------------|
-| `RelationTypeDTOIn` | Input DTO (relation_type, model_collection_id, related_collection_id) |
-| `RelationTypeDTOOut` | + _relation_type_id, cardinality fields, timestamps |
-| `RelationTypeDbRow` | + __is_rest_disabled |
-| `RelationType` | Alias for RelationTypeDbRow |
-| `RelationDTOIn` | Input DTO (related_id, weak_related_id, sort_order, flags, meta) |
-| `RelationDTOOut` | + relation_id, _relation_type_id, model_id, timestamps |
-| `RelationDbRow` | Equals RelationDTOOut |
-| `Relation` | Alias for RelationDbRow |
+| Type                 | Description                                                           |
+| -------------------- | --------------------------------------------------------------------- |
+| `RelationTypeDTOIn`  | Input DTO (relation_type, model_collection_id, related_collection_id) |
+| `RelationTypeDTOOut` | + _relation_type_id, cardinality fields, timestamps                   |
+| `RelationTypeDbRow`  | + __is_rest_disabled                                                  |
+| `RelationType`       | Alias for RelationTypeDbRow                                           |
+| `RelationDTOIn`      | Input DTO (related_id, weak_related_id, sort_order, flags, meta)      |
+| `RelationDTOOut`     | + relation_id, _relation_type_id, model_id, timestamps                |
+| `RelationDbRow`      | Equals RelationDTOOut                                                 |
+| `Relation`           | Alias for RelationDbRow                                               |
 
 ## schema.ts — JSON Schema Extensions
 
-| Type | Description |
-|------|-------------|
-| `SchemaHtmlType` | Union: text, textarea, wysiwyg, number, boolean, select, multiselect, date, datetime, time, color, relation, asset, json, code |
-| `RelationTypeConfig` | Config for relation fields (relation_type, domain, entity, cardinality) |
-| `AssetTypeConfig` | Config for asset fields (accept, maxSize, variants) |
-| `SelectConfig` | Config for select fields (options array) |
-| `SchemaHtmlConfig` | HTML field config (type, _type_config, rows, placeholder, help, readonly, hidden) |
-| `CustomSchemaKeywords` | Custom keywords (_default, _html, _title, _description, _label_source, _unique, _searchable, _order) |
-| `PropertyDefinition` | JSON Schema + custom keywords |
-| `ModelDefinition` | Model type schema (properties, required) |
+| Type                   | Description                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `SchemaHtmlType`       | Union: text, textarea, wysiwyg, number, boolean, select, multiselect, date, datetime, time, color, relation, asset, json, code |
+| `RelationTypeConfig`   | Config for relation fields (relation_type, domain, entity, cardinality)                                                        |
+| `AssetTypeConfig`      | Config for asset fields (accept, maxSize, variants)                                                                            |
+| `SelectConfig`         | Config for select fields (options array)                                                                                       |
+| `SchemaHtmlConfig`     | HTML field config (type, _type_config, rows, placeholder, help, readonly, hidden)                                              |
+| `CustomSchemaKeywords` | Custom keywords (_default, _html, _title, _description, _label_source, _unique, _searchable, _order)                           |
+| `PropertyDefinition`   | JSON Schema + custom keywords                                                                                                  |
+| `ModelDefinition`      | Model type schema (properties, required)                                                                                       |
 
 ## api.ts — API & Query Types
 
-| Type | Description |
-|------|-------------|
-| `PaginationMeta` | Pagination info (limit, offset, total, hasMore) |
-| `ApiResponse<T>` | Generic response wrapper (data, meta) |
-| `ApiListResponse<T>` | List response with pagination and included relations |
-| `QueryOperator` | Filter operators: eq, neq, gt, gte, lt, lte, like, nlike, match, nmatch, is, nis, in, nin, ltree, ancestor, descendant |
-| `QueryCondition` | Single filter condition (field, operator, value) |
-| `QuerySyntax` | Query params (where, search, order, asc, limit, offset) |
+| Type                 | Description                                                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `PaginationMeta`     | Pagination info (limit, offset, total, hasMore)                                                                        |
+| `ApiResponse<T>`     | Generic response wrapper (data, meta)                                                                                  |
+| `ApiListResponse<T>` | List response with pagination and included relations                                                                   |
+| `QueryOperator`      | Filter operators: eq, neq, gt, gte, lt, lte, like, nlike, match, nmatch, is, nis, in, nin, ltree, ancestor, descendant |
+| `QueryCondition`     | Single filter condition (field, operator, value)                                                                       |
+| `QuerySyntax`        | Query params (where, search, order, asc, limit, offset)                                                                |
 
 ## asset.ts — File Attachment Types
 
-| Type | Description |
-|------|-------------|
-| `AssetVariant` | Asset variant (name, width, height, format, url) |
-| `AssetData` | Asset metadata (filename, mimetype, size, url, variants, metadata) |
-| `ModelAsset` | Asset attached to model (asset_id, model_id, field_name, sort_order, data, timestamps) |
+| Type           | Description                                                                            |
+| -------------- | -------------------------------------------------------------------------------------- |
+| `AssetVariant` | Asset variant (name, width, height, format, url)                                       |
+| `AssetData`    | Asset metadata (filename, mimetype, size, url, variants, metadata)                     |
+| `ModelAsset`   | Asset attached to model (asset_id, model_id, field_name, sort_order, data, timestamps) |
 
 ## adapter.ts — Database Adapter Types
 
-| Type | Description |
-|------|-------------|
-| `DbQueryResult<T>` | Query result (rows, rowCount) |
-| `QueryProvider` | DB interface (type: "pg" \| "sqlite", query, each) |
-| `AdapterOptions` | Adapter config (tablePrefix, preInitSql, postInitSql, projectIdFk, resetAll) |
+| Type               | Description                                                                  |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `DbQueryResult<T>` | Query result (rows, rowCount)                                                |
+| `QueryProvider`    | DB interface (type: "pg" \| "sqlite", query, each)                           |
+| `AdapterOptions`   | Adapter config (tablePrefix, preInitSql, postInitSql, projectIdFk, resetAll) |
 
 ## linked-assets.ts — Metadata-Based Asset Linking
 
-| Type | Description |
-|------|-------------|
-| `LinkedAssetOperator` | Match operators: eq, neq, lt, lte, gt, gte, like, ilike, in, nin, ?, descendant |
-| `LinkedAssetValueSource` | Value source: "literal" or "model_field" |
-| `LinkedAssetCondition` | Single matching condition (asset_field, operator, value_source, value) |
-| `LinkedAssetUploadConfig` | Upload config (auto_fill_custom, type, accept, cardinality) |
-| `LinkedAssetUnlinkConfig` | Unlink config (field, confirm) |
-| `LinkedAssetQueryConfig` | Query config (domain, entity, type, conditions, base_conditions) |
-| `LinkedAssetMatchConfig` | Match context (domain, entity, type) |
-| `LinkedAssetRule` | Single rule (id, label, match, asset_query, upload, unlink, enabled, order) |
-| `LinkedAssetsConfig` | Complete config with version and rules array |
+| Type                      | Description                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------- |
+| `LinkedAssetOperator`     | Match operators: eq, neq, lt, lte, gt, gte, like, ilike, in, nin, ?, descendant |
+| `LinkedAssetValueSource`  | Value source: "literal" or "model_field"                                        |
+| `LinkedAssetCondition`    | Single matching condition (asset_field, operator, value_source, value)          |
+| `LinkedAssetUploadConfig` | Upload config (auto_fill_custom, type, accept, cardinality)                     |
+| `LinkedAssetUnlinkConfig` | Unlink config (field, confirm)                                                  |
+| `LinkedAssetQueryConfig`  | Query config (domain, entity, type, conditions, base_conditions)                |
+| `LinkedAssetMatchConfig`  | Match context (domain, entity, type)                                            |
+| `LinkedAssetRule`         | Single rule (id, label, match, asset_query, upload, unlink, enabled, order)     |
+| `LinkedAssetsConfig`      | Complete config with version and rules array                                    |
 
 ## navigation.ts — Admin UI Navigation
 
-| Type | Description |
-|------|-------------|
-| `CollectionTypeEntry` | Type entry within collection (name, schemaTitle) |
-| `ModuleRegistryEntry` | Domain module registry (domain, mount, domainLabel, collections) |
-| `NavConfig` | Navigation customization (overrides, hidden, custom items) |
-| `NavItemDef` | Output nav item (label, href, domain, entity, type, id, folder, icon, group) |
+| Type                  | Description                                                                  |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `CollectionTypeEntry` | Type entry within collection (name, schemaTitle)                             |
+| `ModuleRegistryEntry` | Domain module registry (domain, mount, domainLabel, collections)             |
+| `NavConfig`           | Navigation customization (overrides, hidden, custom items)                   |
+| `NavItemDef`          | Output nav item (label, href, domain, entity, type, id, folder, icon, group) |
 
 ## form-routes.ts — Form Route Overrides
 
-| Type | Description |
-|------|-------------|
-| `HttpMethod` | HTTP methods for forms: "POST", "PUT", "DELETE" |
-| `FormRouteMatch` | Matching context (domain, entity, type, method) with wildcard support |
-| `FormRouteRule` | Single override rule (id, description, match, endpoint, enabled, priority) |
-| `FormRoutesConfig` | Complete config with version and rules array |
-| `FormRouteContext` | Runtime lookup context for route resolution |
+| Type               | Description                                                                |
+| ------------------ | -------------------------------------------------------------------------- |
+| `HttpMethod`       | HTTP methods for forms: "POST", "PUT", "DELETE"                            |
+| `FormRouteMatch`   | Matching context (domain, entity, type, method) with wildcard support      |
+| `FormRouteRule`    | Single override rule (id, description, match, endpoint, enabled, priority) |
+| `FormRoutesConfig` | Complete config with version and rules array                               |
+| `FormRouteContext` | Runtime lookup context for route resolution                                |
 
 ## session.ts — Session & Cart Types
 
-| Type | Description |
-|------|-------------|
-| `CartItem` | Single cart item (product_id, quantity) |
-| `CartData` | Cart contents (items: CartItem[]) |
+| Type           | Description                                  |
+| -------------- | -------------------------------------------- |
+| `CartItem`     | Single cart item (product_id, quantity)      |
+| `CartData`     | Cart contents (items: CartItem[])            |
 | `WishlistItem` | Single wishlist item (product_id, added_at?) |
-| `WishlistData` | Wishlist contents (items: WishlistItem[]) |
-| `SessionData` | Session data (cart, wishlist) |
-| `SessionType` | Type identifier: "session" |
+| `WishlistData` | Wishlist contents (items: WishlistItem[])    |
+| `SessionData`  | Session data (cart, wishlist)                |
+| `SessionType`  | Type identifier: "session"                   |
 
 ## payment.ts — Payment Types
 
-| Type | Description |
-|------|-------------|
-| `PaymentStatus` | Status: pending, completed, failed, refunded |
-| `PaymentData` | Payment data (provider, status, amount, currency, provider_reference) |
-| `PaymentType` | Type identifier: "payment" |
-| `PaymentInitConfig` | Payment initiation config (provider, amount, currency, return_url?) |
-| `PaymentIntent` | Payment initiation result (id, redirect_url, provider_data?) |
-| `PaymentResult` | Payment capture result (provider_reference) |
-| `RefundResult` | Refund result (refund_id) |
-| `WebhookResult` | Webhook processing result (event_type, payment_id?) |
+| Type                | Description                                                           |
+| ------------------- | --------------------------------------------------------------------- |
+| `PaymentStatus`     | Status: pending, completed, failed, refunded                          |
+| `PaymentData`       | Payment data (provider, status, amount, currency, provider_reference) |
+| `PaymentType`       | Type identifier: "payment"                                            |
+| `PaymentInitConfig` | Payment initiation config (provider, amount, currency, return_url?)   |
+| `PaymentIntent`     | Payment initiation result (id, redirect_url, provider_data?)          |
+| `PaymentResult`     | Payment capture result (provider_reference)                           |
+| `RefundResult`      | Refund result (refund_id)                                             |
+| `WebhookResult`     | Webhook processing result (event_type, payment_id?)                   |
 
 ## order.ts — Order Types
 
-| Type | Description |
-|------|-------------|
-| `OrderStatus` | Status: pending, paid, processing, shipped, delivered, cancelled |
-| `CheckoutStage` | Checkout stages: cart, addresses, delivery, confirm, payment, complete |
-| `OrderLineItem` | Line item snapshot (product_id, sku?, name, price, quantity) |
-| `OrderTotals` | Price totals (subtotal, tax, shipping, discount, total) |
-| `DeliveryOptionSnapshot` | Delivery option snapshot (id, name, price, estimated_time?) |
-| `OrderData` | Order data (status, items, currency, totals, addresses, delivery, checkout) |
-| `OrderEventType` | Event types: created, status_changed, payment_added, note_added, cancelled |
-| `OrderEventActor` | Event actor (type: customer/admin/system, id?) |
-| `OrderEventData` | Order event audit trail (event_type, statuses, actor, details?) |
-| `OrderType` | Type identifier: "order" |
-| `OrderEventModelType` | Event type identifier: "event" |
-| `OrderCreateResult` | Order creation result (model_id, data: OrderData) |
+| Type                     | Description                                                                 |
+| ------------------------ | --------------------------------------------------------------------------- |
+| `OrderStatus`            | Status: pending, paid, processing, shipped, delivered, cancelled            |
+| `CheckoutStage`          | Checkout stages: cart, addresses, delivery, confirm, payment, complete      |
+| `OrderLineItem`          | Line item snapshot (product_id, sku?, name, price, quantity)                |
+| `OrderTotals`            | Price totals (subtotal, tax, shipping, discount, total)                     |
+| `DeliveryOptionSnapshot` | Delivery option snapshot (id, name, price, estimated_time?)                 |
+| `OrderData`              | Order data (status, items, currency, totals, addresses, delivery, checkout) |
+| `OrderEventType`         | Event types: created, status_changed, payment_added, note_added, cancelled  |
+| `OrderEventActor`        | Event actor (type: customer/admin/system, id?)                              |
+| `OrderEventData`         | Order event audit trail (event_type, statuses, actor, details?)             |
+| `OrderType`              | Type identifier: "order"                                                    |
+| `OrderEventModelType`    | Event type identifier: "event"                                              |
+| `OrderCreateResult`      | Order creation result (model_id, data: OrderData)                           |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/collection-types",
-	"version": "2.2.0",
+	"version": "2.4.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",