@marianmeres/collection-types 1.8.1 → 1.9.0

package/README.md

@@ -1,3 +1,181 @@
 # @marianmeres/collection-types
 
-Shared type definitions for internal use within the @marianmeres ecosystem. Type-only package with no runtime code.
+Type definitions and schema utilities for the @marianmeres/collection ecosystem.
+
+## Overview
+
+This package provides:
+
+1. **Core Types**: Model, Collection, Relation, Schema definitions
+2. **Domain Types**: Typed interfaces for all stack-xyz domains
+3. **Schema Builder**: `createObjectSchema<T>()` for type-safe schema definitions
+
+## Installation
+
+```typescript
+import type {
+  Model,
+  Collection,
+  UUID,
+  ProductData,
+  CustomerData,
+} 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 |
+
+```typescript
+import type { Model } from "@marianmeres/collection-types";
+import type { ProductData } from "@marianmeres/collection-types";
+
+type ProductModel = Model<ProductData>;
+// ProductModel.data is typed as ProductData
+```
+
+## Domain Types
+
+### 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 |
+
+### 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 |
+
+### 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 |
+
+## Type-Safe Schema Definitions
+
+Use `createObjectSchema<T>()` to catch property typos at compile time.
+
+### The Problem
+
+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"
+  },
+};
+```
+
+### The Solution
+
+```typescript
+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
+  },
+});
+```
+
+### Defining Data Interfaces
+
+Data interfaces must include:
+
+1. **Data fields** with their types
+2. **UI-only fields** (relations) as `never` type
+3. **Index signature** for `Model<T>` compatibility
+
+```typescript
+export interface ProductData {
+  // Data fields
+  name: string;
+  price?: number;
+  sku?: string;
+
+  // UI-only fields (never stored in data)
+  category?: never;
+  images?: never;
+
+  // Index signature for Model<T> compatibility
+  [key: string]: unknown;
+}
+```
+
+### Extended Schemas
+
+For schemas using `__extends`, use `ExtendedSchema`:
+
+```typescript
+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,
+};
+```
+
+## Best Practices
+
+1. Define all domain interfaces in this package
+2. Use `createObjectSchema<T>()` for base schemas
+3. Use `as ExtendedSchema` for `__extends` schemas
+4. Include UI-only fields as `never` type
+5. Keep index signature for Model<T> compatibility
+6. Re-export types from stack package mod.ts
+
+See `workspace/stack-example/README.md` for comprehensive examples.
+
+## License
+
+MIT

package/dist/account.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Account domain types for the stack-account module.
+ *
+ * Includes account, password, and token collection types.
+ */
+/** Account model data */
+export interface AccountData {
+    email: string;
+    roles?: string[];
+    isVerified?: boolean;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}
+/** Password model data (stores hashed passwords) */
+export interface PasswordData {
+    hash: string;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}
+/** Token model data (for auth tokens) */
+export interface TokenData {
+    validFrom?: string;
+    validUntil?: string;
+    roles?: string[];
+    jwt?: string;
+    email?: string;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}

package/dist/account.js

@@ -0,0 +1,6 @@
+/**
+ * Account domain types for the stack-account module.
+ *
+ * Includes account, password, and token collection types.
+ */
+export {};

package/dist/email.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Email domain types for the stack-email module.
+ *
+ * Email log types for audit trail of sent emails.
+ */
+/** Email status values */
+export type EmailStatus = "queued" | "sent" | "failed";
+/** Email model data (audit log entry) */
+export interface EmailData {
+    to?: string;
+    from?: string;
+    subject?: string;
+    body_html?: string;
+    body_text?: string;
+    reply_to?: string;
+    cc?: string;
+    bcc?: string;
+    /** Email delivery status */
+    status?: EmailStatus;
+    /** Transport used (e.g., "smtp", "sendgrid") */
+    transport?: string;
+    /** Timestamp when email was sent */
+    sent_at?: string;
+    /** Error message if delivery failed */
+    error?: string;
+    /** External ID from email provider */
+    external_id?: string;
+    /** Job UID for async email processing */
+    job_uid?: string;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}

package/dist/email.js

@@ -0,0 +1,6 @@
+/**
+ * Email domain types for the stack-email module.
+ *
+ * Email log types for audit trail of sent emails.
+ */
+export {};

package/dist/example.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Example domain types for the stack-example reference module.
+ *
+ * These types are used for testing and demonstrating all collection features
+ * including multiple model types, relations, and various field types.
+ */
+import type { MaybeLocalized } from "./utils.js";
+/** Example model data - default type */
+export interface ExampleDataDefault {
+    name: string;
+    description?: MaybeLocalized<string>;
+    slug: string;
+    release_date?: string;
+    status?: "draft" | "published" | "archived";
+    custom?: Record<string, unknown>;
+    comments?: never;
+    images?: never;
+    global_asset?: never;
+    owner?: never;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}
+/** Example model data - foo type (extends default with string field) */
+export interface ExampleDataFoo extends ExampleDataDefault {
+    foo_specific?: string;
+}
+/** Example model data - bar type (extends default with number and date fields) */
+export interface ExampleDataBar extends ExampleDataDefault {
+    bar_specific?: number;
+    bar_date?: string;
+}
+/** Union of all example data types */
+export type ExampleData = ExampleDataDefault | ExampleDataFoo | ExampleDataBar;
+/** Comment model data for testing strong relations */
+export interface CommentData {
+    body: string;
+    author_name?: string;
+    created_at?: string;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}

package/dist/example.js

@@ -0,0 +1,7 @@
+/**
+ * Example domain types for the stack-example reference module.
+ *
+ * These types are used for testing and demonstrating all collection features
+ * including multiple model types, relations, and various field types.
+ */
+export {};

package/dist/mod.d.ts

@@ -1,19 +1,28 @@
 /**
  * @module @marianmeres/collection-types
  *
- * Type definitions for the collection management system.
- * Pure interfaces with no runtime code - safe for type-only imports.
+ * Type definitions and schema utilities for the collection management system.
+ *
+ * Includes:
+ * - Core types: Model, Collection, Relation, Schema
+ * - Domain types: Account, Product, Order, Customer, Session, etc.
+ * - Schema builder: createObjectSchema<T>() for type-safe schema definitions
  *
  * @example
  * ```typescript
+ * // Type-only imports
  * import type {
  *   Model,
  *   Collection,
- *   Relation,
- *   RelationType,
- *   PropertyDefinition,
- *   ApiResponse,
  *   UUID,
+ *   ProductData,
+ *   CustomerData,
+ * } from "@marianmeres/collection-types";
+ *
+ * // Schema builder (runtime import)
+ * import {
+ *   createObjectSchema,
+ *   type ExtendedSchema,
  * } from "@marianmeres/collection-types";
  * ```
  */
@@ -31,3 +40,10 @@ export * from "./customer.js";
 export * from "./order.js";
 export * from "./payment.js";
 export * from "./external-domain.js";
+export * from "./account.js";
+export * from "./product.js";
+export * from "./project.js";
+export * from "./template.js";
+export * from "./email.js";
+export * from "./example.js";
+export * from "./schema-builder.js";

package/dist/mod.js

@@ -1,19 +1,28 @@
 /**
  * @module @marianmeres/collection-types
  *
- * Type definitions for the collection management system.
- * Pure interfaces with no runtime code - safe for type-only imports.
+ * Type definitions and schema utilities for the collection management system.
+ *
+ * Includes:
+ * - Core types: Model, Collection, Relation, Schema
+ * - Domain types: Account, Product, Order, Customer, Session, etc.
+ * - Schema builder: createObjectSchema<T>() for type-safe schema definitions
  *
  * @example
  * ```typescript
+ * // Type-only imports
  * import type {
  *   Model,
  *   Collection,
- *   Relation,
- *   RelationType,
- *   PropertyDefinition,
- *   ApiResponse,
  *   UUID,
+ *   ProductData,
+ *   CustomerData,
+ * } from "@marianmeres/collection-types";
+ *
+ * // Schema builder (runtime import)
+ * import {
+ *   createObjectSchema,
+ *   type ExtendedSchema,
  * } from "@marianmeres/collection-types";
  * ```
  */
@@ -40,3 +49,17 @@ export * from "./order.js";
 export * from "./payment.js";
 // Cross-domain reference support
 export * from "./external-domain.js";
+// Account domain types
+export * from "./account.js";
+// Product domain types
+export * from "./product.js";
+// Project/config domain types
+export * from "./project.js";
+// Template domain types
+export * from "./template.js";
+// Email domain types
+export * from "./email.js";
+// Example domain types (reference implementation)
+export * from "./example.js";
+// Schema builder utilities (type-safe schema definitions)
+export * from "./schema-builder.js";

package/dist/product.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Product domain types for the stack-product module.
+ *
+ * Includes product and category collection types.
+ */
+import type { MaybeLocalized } from "./utils.js";
+/** Product model data */
+export interface ProductData {
+    name: string;
+    sku?: string;
+    /** Price in cents (integer) */
+    price?: number;
+    slug?: string;
+    short_description?: MaybeLocalized<string>;
+    description?: MaybeLocalized<string>;
+    /** Whether product has an associated image */
+    has_image?: boolean;
+    custom?: Record<string, unknown>;
+    category?: never;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}
+/** Category model data */
+export interface CategoryData {
+    name: string;
+    slug?: string;
+    short_description?: MaybeLocalized<string>;
+    description?: MaybeLocalized<string>;
+    custom?: Record<string, unknown>;
+    images?: never;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}

package/dist/product.js

@@ -0,0 +1,6 @@
+/**
+ * Product domain types for the stack-product module.
+ *
+ * Includes product and category collection types.
+ */
+export {};

package/dist/project.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Project domain types for the stack-project module.
+ *
+ * Includes config collection types with default, _system, and _rbac subtypes.
+ */
+/** Config model data - default type */
+export interface ConfigDataDefault {
+    key: string;
+    value?: unknown;
+    internal_description?: string;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}
+/** Permission definition for RBAC */
+export interface RbacPermission {
+    name: string;
+    description?: string;
+}
+/** Role definition for RBAC */
+export interface RbacRole {
+    name: string;
+    description?: string;
+    permissions?: string[];
+}
+/** Group definition for RBAC */
+export interface RbacGroup {
+    name: string;
+    description?: string;
+    roles?: string[];
+}
+/** Config model data - _rbac type (extends default) */
+export interface ConfigDataRbac extends ConfigDataDefault {
+    groups?: RbacGroup[];
+    roles?: RbacRole[];
+    permissions?: RbacPermission[];
+}
+/** Union of all config data types */
+export type ConfigData = ConfigDataDefault | ConfigDataRbac;

package/dist/project.js

@@ -0,0 +1,6 @@
+/**
+ * Project domain types for the stack-project module.
+ *
+ * Includes config collection types with default, _system, and _rbac subtypes.
+ */
+export {};

package/dist/schema-builder.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Type-safe schema builder utilities.
+ *
+ * Provides compile-time validation that JSON Schema property keys
+ * match the corresponding TypeScript interface.
+ */
+import type { MaybeLocalized } from "./utils.js";
+import type { PropertyDefinition } from "./schema.js";
+/**
+ * Removes index signature from a type, keeping only explicitly defined keys.
+ * This allows createObjectSchema to validate keys even when the interface
+ * has [key: string]: unknown for Model<T> compatibility.
+ */
+type KnownKeys<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+/** Type-safe schema properties - only known keys from T allowed */
+type SchemaProperties<T> = {
+    [K in keyof KnownKeys<T>]?: PropertyDefinition;
+};
+/** Type-safe object schema definition */
+export type ObjectSchema<T> = {
+    type: "object";
+    required?: (keyof KnownKeys<T>)[];
+    properties: SchemaProperties<T>;
+    additionalProperties?: boolean;
+    _title?: MaybeLocalized<string>;
+    _description?: MaybeLocalized<string>;
+    _searchable?: boolean;
+};
+/** Extended schema (loose typing for __extends patterns) */
+export type ExtendedSchema = {
+    __extends: string;
+    properties?: Record<string, PropertyDefinition>;
+    _title?: MaybeLocalized<string>;
+    _description?: MaybeLocalized<string>;
+};
+/**
+ * Create a type-safe object schema.
+ * TypeScript will error if property keys don't exist in T.
+ *
+ * @example
+ * ```typescript
+ * import { createObjectSchema } from "@marianmeres/collection-types";
+ *
+ * interface ProductData {
+ *   name: string;
+ *   price: number;
+ * }
+ *
+ * const schema = createObjectSchema<ProductData>({
+ *   type: "object",
+ *   required: ["name", "price"],
+ *   properties: {
+ *     name: { type: "string" },     // OK
+ *     price: { type: "number" },    // OK
+ *     namex: { type: "string" },    // Error: 'namex' not in ProductData
+ *   },
+ * });
+ * ```
+ */
+export declare function createObjectSchema<T>(schema: ObjectSchema<T>): ObjectSchema<T>;
+export {};

package/dist/schema-builder.js

@@ -0,0 +1,36 @@
+/**
+ * Type-safe schema builder utilities.
+ *
+ * Provides compile-time validation that JSON Schema property keys
+ * match the corresponding TypeScript interface.
+ */
+// -----------------------------------------------------------------------------
+// Functions
+// -----------------------------------------------------------------------------
+/**
+ * Create a type-safe object schema.
+ * TypeScript will error if property keys don't exist in T.
+ *
+ * @example
+ * ```typescript
+ * import { createObjectSchema } from "@marianmeres/collection-types";
+ *
+ * interface ProductData {
+ *   name: string;
+ *   price: number;
+ * }
+ *
+ * const schema = createObjectSchema<ProductData>({
+ *   type: "object",
+ *   required: ["name", "price"],
+ *   properties: {
+ *     name: { type: "string" },     // OK
+ *     price: { type: "number" },    // OK
+ *     namex: { type: "string" },    // Error: 'namex' not in ProductData
+ *   },
+ * });
+ * ```
+ */
+export function createObjectSchema(schema) {
+    return schema;
+}

package/dist/template.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Template domain types for the stack-template module.
+ *
+ * Templates use Handlebars for variable substitution and MJML for email HTML rendering.
+ */
+/** Template model data */
+export interface TemplateData {
+    slug: string;
+    name: string;
+    description?: string;
+    /** Email subject line (Handlebars template) */
+    subject?: string;
+    /** Email body in MJML format (Handlebars template) */
+    body_mjml?: string;
+    /** Plain text email body (Handlebars template) */
+    body_text?: string;
+    /** JSON Schema for template variables validation */
+    variables_schema?: Record<string, unknown>;
+    /** Sample data for template preview */
+    sample_data?: Record<string, unknown>;
+    /** Template language code */
+    lang?: string;
+    /** Whether template is active */
+    is_active?: boolean;
+    /** Index signature for Model<T> compatibility */
+    [key: string]: unknown;
+}

package/dist/template.js

@@ -0,0 +1,6 @@
+/**
+ * Template domain types for the stack-template module.
+ *
+ * Templates use Handlebars for variable substitution and MJML for email HTML rendering.
+ */
+export {};

package/package.json

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