@objectstack/spec 0.3.2 → 0.4.1

package/dist/data/hook.zod.d.ts

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+/**
+ * Hook Lifecycle Events
+ * Defines the interception points in the ObjectQL execution pipeline.
+ */
+export declare const HookEvent: z.ZodEnum<["beforeFind", "afterFind", "beforeFindOne", "afterFindOne", "beforeCount", "afterCount", "beforeAggregate", "afterAggregate", "beforeInsert", "afterInsert", "beforeUpdate", "afterUpdate", "beforeDelete", "afterDelete", "beforeUpdateMany", "afterUpdateMany", "beforeDeleteMany", "afterDeleteMany"]>;
+/**
+ * Hook Definition Schema
+ *
+ * Hooks serve as the "Logic Layer" in ObjectStack, allowing developers to
+ * inject custom code during the data access lifecycle.
+ *
+ * Use cases:
+ * - Data Enrichment (Default values, Calculated fields)
+ * - Validation (Complex business rules)
+ * - Side Effects (Sending emails, Syncing to external systems)
+ * - Security (Filtering data based on context)
+ */
+export declare const HookSchema: z.ZodObject<{
+    /**
+     * Unique identifier for the hook
+     * Required for debugging and overriding.
+     */
+    name: z.ZodString;
+    /**
+     * Human readable label
+     */
+    label: z.ZodOptional<z.ZodString>;
+    /**
+     * Target Object(s)
+     * can be:
+     * - Single object: "account"
+     * - List of objects: ["account", "contact"]
+     * - Wildcard: "*" (All objects)
+     */
+    object: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+    /**
+     * Events to subscribe to
+     * Combinations of timing (before/after) and action (find/insert/update/delete/etc)
+     */
+    events: z.ZodArray<z.ZodEnum<["beforeFind", "afterFind", "beforeFindOne", "afterFindOne", "beforeCount", "afterCount", "beforeAggregate", "afterAggregate", "beforeInsert", "afterInsert", "beforeUpdate", "afterUpdate", "beforeDelete", "afterDelete", "beforeUpdateMany", "afterUpdateMany", "beforeDeleteMany", "afterDeleteMany"]>, "many">;
+    /**
+     * Handler Logic
+     * Reference to a registered function in the plugin system OR a direct function (runtime only).
+     */
+    handler: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodAny]>>;
+    /**
+     * Execution Order
+     * Lower numbers run first.
+     * - System Hooks: 0-99
+     * - App Hooks: 100-999
+     * - User Hooks: 1000+
+     */
+    priority: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Async / Background Execution
+     * If true, the hook runs in the background and does not block the transaction.
+     * Only applicable for 'after*' events.
+     * Default: false (Blocking)
+     */
+    async: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Error Policy
+     * What to do if the hook throws an exception?
+     * - abort: Rollback transaction (if blocking)
+     * - log: Log error and continue
+     */
+    onError: z.ZodDefault<z.ZodEnum<["abort", "log"]>>;
+}, "strip", z.ZodTypeAny, {
+    object: string | string[];
+    name: string;
+    events: ("beforeFind" | "afterFind" | "beforeFindOne" | "afterFindOne" | "beforeCount" | "afterCount" | "beforeAggregate" | "afterAggregate" | "beforeInsert" | "afterInsert" | "beforeUpdate" | "afterUpdate" | "beforeDelete" | "afterDelete" | "beforeUpdateMany" | "afterUpdateMany" | "beforeDeleteMany" | "afterDeleteMany")[];
+    async: boolean;
+    priority: number;
+    onError: "abort" | "log";
+    label?: string | undefined;
+    handler?: any;
+}, {
+    object: string | string[];
+    name: string;
+    events: ("beforeFind" | "afterFind" | "beforeFindOne" | "afterFindOne" | "beforeCount" | "afterCount" | "beforeAggregate" | "afterAggregate" | "beforeInsert" | "afterInsert" | "beforeUpdate" | "afterUpdate" | "beforeDelete" | "afterDelete" | "beforeUpdateMany" | "afterUpdateMany" | "beforeDeleteMany" | "afterDeleteMany")[];
+    label?: string | undefined;
+    async?: boolean | undefined;
+    handler?: any;
+    priority?: number | undefined;
+    onError?: "abort" | "log" | undefined;
+}>;
+/**
+ * Hook Runtime Context
+ * Defines what is available to the hook handler during execution.
+ *
+ * Best Practices:
+ * - **Immutability**: `object`, `event`, `id` are immutable.
+ * - **Mutability**: `input` and `result` are mutable to allow transformation.
+ * - **Encapsulation**: `session` isolates auth info; `transaction` ensures atomicity.
+ */
+export declare const HookContextSchema: z.ZodObject<{
+    /** Tracing ID */
+    id: z.ZodOptional<z.ZodString>;
+    /** Target Object Name */
+    object: z.ZodString;
+    /** Current Lifecycle Event */
+    event: z.ZodEnum<["beforeFind", "afterFind", "beforeFindOne", "afterFindOne", "beforeCount", "afterCount", "beforeAggregate", "afterAggregate", "beforeInsert", "afterInsert", "beforeUpdate", "afterUpdate", "beforeDelete", "afterDelete", "beforeUpdateMany", "afterUpdateMany", "beforeDeleteMany", "afterDeleteMany"]>;
+    /**
+     * Input Parameters (Mutable)
+     * Modify this to change the behavior of the operation.
+     *
+     * - find: { query: QueryAST, options: DriverOptions }
+     * - insert: { doc: Record, options: DriverOptions }
+     * - update: { id: ID, doc: Record, options: DriverOptions }
+     * - delete: { id: ID, options: DriverOptions }
+     * - updateMany: { query: QueryAST, doc: Record, options: DriverOptions }
+     * - deleteMany: { query: QueryAST, options: DriverOptions }
+     */
+    input: z.ZodRecord<z.ZodString, z.ZodAny>;
+    /**
+     * Operation Result (Mutable)
+     * Available in 'after*' events. Modify this to transform the output.
+     */
+    result: z.ZodOptional<z.ZodAny>;
+    /**
+     * Data Snapshot
+     * The state of the record BEFORE the operation (for update/delete).
+     */
+    previous: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /**
+     * Execution Session
+     * Contains authentication and tenancy information.
+     */
+    session: z.ZodOptional<z.ZodObject<{
+        userId: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
+        roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        userId?: string | undefined;
+        tenantId?: string | undefined;
+        roles?: string[] | undefined;
+        accessToken?: string | undefined;
+    }, {
+        userId?: string | undefined;
+        tenantId?: string | undefined;
+        roles?: string[] | undefined;
+        accessToken?: string | undefined;
+    }>>;
+    /**
+     * Transaction Handle
+     * If the operation is part of a transaction, use this handle for side-effects.
+     */
+    transaction: z.ZodOptional<z.ZodAny>;
+    /**
+     * Engine Access
+     * Reference to the ObjectQL engine for performing side effects.
+     */
+    ql: z.ZodAny;
+}, "strip", z.ZodTypeAny, {
+    object: string;
+    event: "beforeFind" | "afterFind" | "beforeFindOne" | "afterFindOne" | "beforeCount" | "afterCount" | "beforeAggregate" | "afterAggregate" | "beforeInsert" | "afterInsert" | "beforeUpdate" | "afterUpdate" | "beforeDelete" | "afterDelete" | "beforeUpdateMany" | "afterUpdateMany" | "beforeDeleteMany" | "afterDeleteMany";
+    input: Record<string, any>;
+    id?: string | undefined;
+    result?: any;
+    previous?: Record<string, any> | undefined;
+    session?: {
+        userId?: string | undefined;
+        tenantId?: string | undefined;
+        roles?: string[] | undefined;
+        accessToken?: string | undefined;
+    } | undefined;
+    transaction?: any;
+    ql?: any;
+}, {
+    object: string;
+    event: "beforeFind" | "afterFind" | "beforeFindOne" | "afterFindOne" | "beforeCount" | "afterCount" | "beforeAggregate" | "afterAggregate" | "beforeInsert" | "afterInsert" | "beforeUpdate" | "afterUpdate" | "beforeDelete" | "afterDelete" | "beforeUpdateMany" | "afterUpdateMany" | "beforeDeleteMany" | "afterDeleteMany";
+    input: Record<string, any>;
+    id?: string | undefined;
+    result?: any;
+    previous?: Record<string, any> | undefined;
+    session?: {
+        userId?: string | undefined;
+        tenantId?: string | undefined;
+        roles?: string[] | undefined;
+        accessToken?: string | undefined;
+    } | undefined;
+    transaction?: any;
+    ql?: any;
+}>;
+export type Hook = z.input<typeof HookSchema>;
+export type ResolvedHook = z.output<typeof HookSchema>;
+export type HookEventType = z.infer<typeof HookEvent>;
+export type HookContext = z.infer<typeof HookContextSchema>;
+//# sourceMappingURL=hook.zod.d.ts.map

package/dist/data/hook.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.zod.d.ts","sourceRoot":"","sources":["../../src/data/hook.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,SAAS,sTAepB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU;IACrB;;;OAGG;;IAGH;;OAEG;;IAGH;;;;;;OAMG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;;;;OAMG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;IAC5B,iBAAiB;;IAGjB,yBAAyB;;IAGzB,8BAA8B;;IAG9B;;;;;;;;;;OAUG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;;;;;;;;;;;;;;;;IAQH;;;OAGG;;IAGH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AACvD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/data/hook.zod.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookContextSchema = exports.HookSchema = exports.HookEvent = void 0;
+const zod_1 = require("zod");
+/**
+ * Hook Lifecycle Events
+ * Defines the interception points in the ObjectQL execution pipeline.
+ */
+exports.HookEvent = zod_1.z.enum([
+    // Read Operations
+    'beforeFind', 'afterFind',
+    'beforeFindOne', 'afterFindOne',
+    'beforeCount', 'afterCount',
+    'beforeAggregate', 'afterAggregate',
+    // Write Operations
+    'beforeInsert', 'afterInsert',
+    'beforeUpdate', 'afterUpdate',
+    'beforeDelete', 'afterDelete',
+    // Bulk Operations (Query-based)
+    'beforeUpdateMany', 'afterUpdateMany',
+    'beforeDeleteMany', 'afterDeleteMany',
+]);
+/**
+ * Hook Definition Schema
+ *
+ * Hooks serve as the "Logic Layer" in ObjectStack, allowing developers to
+ * inject custom code during the data access lifecycle.
+ *
+ * Use cases:
+ * - Data Enrichment (Default values, Calculated fields)
+ * - Validation (Complex business rules)
+ * - Side Effects (Sending emails, Syncing to external systems)
+ * - Security (Filtering data based on context)
+ */
+exports.HookSchema = zod_1.z.object({
+    /**
+     * Unique identifier for the hook
+     * Required for debugging and overriding.
+     */
+    name: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Hook unique name (snake_case)'),
+    /**
+     * Human readable label
+     */
+    label: zod_1.z.string().optional().describe('Description of what this hook does'),
+    /**
+     * Target Object(s)
+     * can be:
+     * - Single object: "account"
+     * - List of objects: ["account", "contact"]
+     * - Wildcard: "*" (All objects)
+     */
+    object: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).describe('Target object(s)'),
+    /**
+     * Events to subscribe to
+     * Combinations of timing (before/after) and action (find/insert/update/delete/etc)
+     */
+    events: zod_1.z.array(exports.HookEvent).describe('Lifecycle events'),
+    /**
+     * Handler Logic
+     * Reference to a registered function in the plugin system OR a direct function (runtime only).
+     */
+    handler: zod_1.z.union([zod_1.z.string(), zod_1.z.any()]).optional().describe('Function handler name or direct function'),
+    /**
+     * Execution Order
+     * Lower numbers run first.
+     * - System Hooks: 0-99
+     * - App Hooks: 100-999
+     * - User Hooks: 1000+
+     */
+    priority: zod_1.z.number().default(100).describe('Execution priority'),
+    /**
+     * Async / Background Execution
+     * If true, the hook runs in the background and does not block the transaction.
+     * Only applicable for 'after*' events.
+     * Default: false (Blocking)
+     */
+    async: zod_1.z.boolean().default(false).describe('Run specifically as fire-and-forget'),
+    /**
+     * Error Policy
+     * What to do if the hook throws an exception?
+     * - abort: Rollback transaction (if blocking)
+     * - log: Log error and continue
+     */
+    onError: zod_1.z.enum(['abort', 'log']).default('abort').describe('Error handling strategy'),
+});
+/**
+ * Hook Runtime Context
+ * Defines what is available to the hook handler during execution.
+ *
+ * Best Practices:
+ * - **Immutability**: `object`, `event`, `id` are immutable.
+ * - **Mutability**: `input` and `result` are mutable to allow transformation.
+ * - **Encapsulation**: `session` isolates auth info; `transaction` ensures atomicity.
+ */
+exports.HookContextSchema = zod_1.z.object({
+    /** Tracing ID */
+    id: zod_1.z.string().optional().describe('Unique execution ID for tracing'),
+    /** Target Object Name */
+    object: zod_1.z.string(),
+    /** Current Lifecycle Event */
+    event: exports.HookEvent,
+    /**
+     * Input Parameters (Mutable)
+     * Modify this to change the behavior of the operation.
+     *
+     * - find: { query: QueryAST, options: DriverOptions }
+     * - insert: { doc: Record, options: DriverOptions }
+     * - update: { id: ID, doc: Record, options: DriverOptions }
+     * - delete: { id: ID, options: DriverOptions }
+     * - updateMany: { query: QueryAST, doc: Record, options: DriverOptions }
+     * - deleteMany: { query: QueryAST, options: DriverOptions }
+     */
+    input: zod_1.z.record(zod_1.z.any()).describe('Mutable input parameters'),
+    /**
+     * Operation Result (Mutable)
+     * Available in 'after*' events. Modify this to transform the output.
+     */
+    result: zod_1.z.any().optional().describe('Operation result (After hooks only)'),
+    /**
+     * Data Snapshot
+     * The state of the record BEFORE the operation (for update/delete).
+     */
+    previous: zod_1.z.record(zod_1.z.any()).optional().describe('Record state before operation'),
+    /**
+     * Execution Session
+     * Contains authentication and tenancy information.
+     */
+    session: zod_1.z.object({
+        userId: zod_1.z.string().optional(),
+        tenantId: zod_1.z.string().optional(),
+        roles: zod_1.z.array(zod_1.z.string()).optional(),
+        accessToken: zod_1.z.string().optional(),
+    }).optional().describe('Current session context'),
+    /**
+     * Transaction Handle
+     * If the operation is part of a transaction, use this handle for side-effects.
+     */
+    transaction: zod_1.z.any().optional().describe('Database transaction handle'),
+    /**
+     * Engine Access
+     * Reference to the ObjectQL engine for performing side effects.
+     */
+    ql: zod_1.z.any().describe('ObjectQL Engine Reference'),
+});

package/dist/data/index.d.ts

@@ -1,21 +1,8 @@
-/**
- * Data Protocol Exports
- *
- * Core Business Logic & Data Modeling
- * - Object, Field, Validation
- * - Query (AST), Mapping (ETL)
- * - Permission, Sharing, Flow
- */
-export * from './field.zod';
+export * from './query.zod';
+export * from './filter.zod';
 export * from './object.zod';
+export * from './field.zod';
 export * from './validation.zod';
-export * from './permission.zod';
-export * from './sharing.zod';
-export * from './workflow.zod';
-export * from './flow.zod';
+export * from './hook.zod';
 export * from './dataset.zod';
-export * from './query.zod';
-export * from './filter.zod';
-export * from './mapping.zod';
-export * from './trigger.zod';
 //# sourceMappingURL=index.d.ts.map

package/dist/data/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAE3B,cAAc,eAAe,CAAC"}

package/dist/data/index.js

@@ -1,12 +1,4 @@
 "use strict";
-/**
- * Data Protocol Exports
- *
- * Core Business Logic & Data Modeling
- * - Object, Field, Validation
- * - Query (AST), Mapping (ETL)
- * - Permission, Sharing, Flow
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -22,15 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./field.zod"), exports);
+__exportStar(require("./query.zod"), exports);
+__exportStar(require("./filter.zod"), exports);
 __exportStar(require("./object.zod"), exports);
+__exportStar(require("./field.zod"), exports);
 __exportStar(require("./validation.zod"), exports);
-__exportStar(require("./permission.zod"), exports);
-__exportStar(require("./sharing.zod"), exports);
-__exportStar(require("./workflow.zod"), exports);
-__exportStar(require("./flow.zod"), exports);
+__exportStar(require("./hook.zod"), exports);
 __exportStar(require("./dataset.zod"), exports);
-__exportStar(require("./query.zod"), exports);
-__exportStar(require("./filter.zod"), exports);
-__exportStar(require("./mapping.zod"), exports);
-__exportStar(require("./trigger.zod"), exports);