@objectstack/spec 0.1.1 → 0.1.2

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

@@ -0,0 +1,354 @@
+import { z } from 'zod';
+/**
+ * Trigger Action Enum
+ *
+ * Defines the database operation that triggered the execution.
+ */
+export declare const TriggerAction: z.ZodEnum<["insert", "update", "delete"]>;
+/**
+ * Trigger Timing Enum
+ *
+ * Defines when the trigger executes relative to the database operation.
+ */
+export declare const TriggerTiming: z.ZodEnum<["before", "after"]>;
+/**
+ * Trigger Context Schema
+ *
+ * This defines the runtime context available to trigger code during execution.
+ * Standardizes how trigger code is written and enables AI code generation.
+ *
+ * Triggers are business logic hooks that execute before or after database operations.
+ * They can validate data, set defaults, update related records, or prevent operations.
+ *
+ * @example Before Insert Trigger
+ * export default {
+ *   timing: 'before',
+ *   action: 'insert',
+ *   execute: async (context: TriggerContext) => {
+ *     // Set default values
+ *     if (!context.doc.status) {
+ *       context.doc.status = 'active';
+ *     }
+ *
+ *     // Validation
+ *     if (!context.doc.email) {
+ *       context.addError('Email is required');
+ *     }
+ *   }
+ * };
+ *
+ * @example After Update Trigger
+ * export default {
+ *   timing: 'after',
+ *   action: 'update',
+ *   execute: async (context: TriggerContext) => {
+ *     // Update related records
+ *     if (context.getOldValue('status') !== context.doc.status) {
+ *       await context.ql.object('activity_log').create({
+ *         record_id: context.doc.id,
+ *         message: `Status changed from ${context.getOldValue('status')} to ${context.doc.status}`,
+ *         user_id: context.userId,
+ *       });
+ *     }
+ *   }
+ * };
+ */
+export declare const TriggerContextSchema: z.ZodObject<{
+    /**
+     * The database operation that triggered execution.
+     * One of: 'insert', 'update', 'delete'
+     */
+    action: z.ZodEnum<["insert", "update", "delete"]>;
+    /**
+     * When the trigger executes relative to the operation.
+     * - 'before': Execute before database operation (can modify doc, prevent operation)
+     * - 'after': Execute after database operation (can trigger side effects)
+     */
+    timing: z.ZodEnum<["before", "after"]>;
+    /**
+     * The current document/record being operated on.
+     *
+     * For 'before' triggers: Can be modified to change what gets saved.
+     * For 'after' triggers: Contains the final saved state (read-only).
+     * For 'delete' triggers: Contains the record being deleted.
+     */
+    doc: z.ZodRecord<z.ZodString, z.ZodAny>;
+    /**
+     * The document state before the current operation.
+     *
+     * Only available for 'update' and 'delete' operations.
+     * Null for 'insert' operations.
+     *
+     * Use this to detect what changed in an update trigger.
+     */
+    previousDoc: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /**
+     * ID of the user performing the operation.
+     */
+    userId: z.ZodString;
+    /**
+     * Complete user record of the user performing the operation.
+     * Contains fields like name, email, roles, etc.
+     */
+    user: z.ZodRecord<z.ZodString, z.ZodAny>;
+    /**
+     * ObjectQL data access API.
+     * Use this to query or modify other records.
+     *
+     * @example
+     * await context.ql.object('account').findOne(context.doc.account_id);
+     * await context.ql.object('activity').create({ ... });
+     */
+    ql: z.ZodAny;
+    /**
+     * Logging interface.
+     * Use this for debugging and auditing.
+     *
+     * @example
+     * context.logger.info('Trigger executed', { recordId: context.doc.id });
+     * context.logger.error('Validation failed', { error });
+     */
+    logger: z.ZodAny;
+    /**
+     * Add a validation error.
+     * For 'before' triggers only - prevents the operation from completing.
+     *
+     * @param message - Error message to display
+     * @param field - Optional field name the error relates to
+     *
+     * @example
+     * if (context.doc.amount < 0) {
+     *   context.addError('Amount must be positive', 'amount');
+     * }
+     */
+    addError: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodString>], z.ZodUnknown>, z.ZodVoid>;
+    /**
+     * Get the old value of a field.
+     * Helper function for 'update' triggers to easily compare old vs new values.
+     *
+     * @param fieldName - Name of the field
+     * @returns Previous value of the field, or undefined if not available
+     *
+     * @example
+     * if (context.getOldValue('status') !== context.doc.status) {
+     *   // Status changed
+     * }
+     */
+    getOldValue: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    user: Record<string, any>;
+    action: "update" | "delete" | "insert";
+    timing: "before" | "after";
+    doc: Record<string, any>;
+    userId: string;
+    addError: (args_0: string, args_1: string | undefined, ...args: unknown[]) => void;
+    getOldValue: (args_0: string, ...args: unknown[]) => any;
+    previousDoc?: Record<string, any> | undefined;
+    ql?: any;
+    logger?: any;
+}, {
+    user: Record<string, any>;
+    action: "update" | "delete" | "insert";
+    timing: "before" | "after";
+    doc: Record<string, any>;
+    userId: string;
+    addError: (args_0: string, args_1: string | undefined, ...args: unknown[]) => void;
+    getOldValue: (args_0: string, ...args: unknown[]) => any;
+    previousDoc?: Record<string, any> | undefined;
+    ql?: any;
+    logger?: any;
+}>;
+/**
+ * Trigger Definition Schema
+ *
+ * Complete definition of a trigger including metadata and execution function.
+ */
+export declare const TriggerSchema: z.ZodObject<{
+    /**
+     * Unique trigger name.
+     */
+    name: z.ZodString;
+    /**
+     * Object this trigger is attached to.
+     */
+    object: z.ZodString;
+    /**
+     * Trigger timing.
+     */
+    timing: z.ZodEnum<["before", "after"]>;
+    /**
+     * Trigger action(s).
+     * Can be a single action or array of actions.
+     */
+    action: z.ZodUnion<[z.ZodEnum<["insert", "update", "delete"]>, z.ZodArray<z.ZodEnum<["insert", "update", "delete"]>, "many">]>;
+    /**
+     * Trigger execution function.
+     * Receives TriggerContext and performs the business logic.
+     */
+    execute: z.ZodFunction<z.ZodTuple<[z.ZodObject<{
+        /**
+         * The database operation that triggered execution.
+         * One of: 'insert', 'update', 'delete'
+         */
+        action: z.ZodEnum<["insert", "update", "delete"]>;
+        /**
+         * When the trigger executes relative to the operation.
+         * - 'before': Execute before database operation (can modify doc, prevent operation)
+         * - 'after': Execute after database operation (can trigger side effects)
+         */
+        timing: z.ZodEnum<["before", "after"]>;
+        /**
+         * The current document/record being operated on.
+         *
+         * For 'before' triggers: Can be modified to change what gets saved.
+         * For 'after' triggers: Contains the final saved state (read-only).
+         * For 'delete' triggers: Contains the record being deleted.
+         */
+        doc: z.ZodRecord<z.ZodString, z.ZodAny>;
+        /**
+         * The document state before the current operation.
+         *
+         * Only available for 'update' and 'delete' operations.
+         * Null for 'insert' operations.
+         *
+         * Use this to detect what changed in an update trigger.
+         */
+        previousDoc: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        /**
+         * ID of the user performing the operation.
+         */
+        userId: z.ZodString;
+        /**
+         * Complete user record of the user performing the operation.
+         * Contains fields like name, email, roles, etc.
+         */
+        user: z.ZodRecord<z.ZodString, z.ZodAny>;
+        /**
+         * ObjectQL data access API.
+         * Use this to query or modify other records.
+         *
+         * @example
+         * await context.ql.object('account').findOne(context.doc.account_id);
+         * await context.ql.object('activity').create({ ... });
+         */
+        ql: z.ZodAny;
+        /**
+         * Logging interface.
+         * Use this for debugging and auditing.
+         *
+         * @example
+         * context.logger.info('Trigger executed', { recordId: context.doc.id });
+         * context.logger.error('Validation failed', { error });
+         */
+        logger: z.ZodAny;
+        /**
+         * Add a validation error.
+         * For 'before' triggers only - prevents the operation from completing.
+         *
+         * @param message - Error message to display
+         * @param field - Optional field name the error relates to
+         *
+         * @example
+         * if (context.doc.amount < 0) {
+         *   context.addError('Amount must be positive', 'amount');
+         * }
+         */
+        addError: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodString>], z.ZodUnknown>, z.ZodVoid>;
+        /**
+         * Get the old value of a field.
+         * Helper function for 'update' triggers to easily compare old vs new values.
+         *
+         * @param fieldName - Name of the field
+         * @returns Previous value of the field, or undefined if not available
+         *
+         * @example
+         * if (context.getOldValue('status') !== context.doc.status) {
+         *   // Status changed
+         * }
+         */
+        getOldValue: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>;
+    }, "strip", z.ZodTypeAny, {
+        user: Record<string, any>;
+        action: "update" | "delete" | "insert";
+        timing: "before" | "after";
+        doc: Record<string, any>;
+        userId: string;
+        addError: (args_0: string, args_1: string | undefined, ...args: unknown[]) => void;
+        getOldValue: (args_0: string, ...args: unknown[]) => any;
+        previousDoc?: Record<string, any> | undefined;
+        ql?: any;
+        logger?: any;
+    }, {
+        user: Record<string, any>;
+        action: "update" | "delete" | "insert";
+        timing: "before" | "after";
+        doc: Record<string, any>;
+        userId: string;
+        addError: (args_0: string, args_1: string | undefined, ...args: unknown[]) => void;
+        getOldValue: (args_0: string, ...args: unknown[]) => any;
+        previousDoc?: Record<string, any> | undefined;
+        ql?: any;
+        logger?: any;
+    }>], z.ZodUnknown>, z.ZodPromise<z.ZodVoid>>;
+    /**
+     * Optional description of what the trigger does.
+     */
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * Whether the trigger is active.
+     */
+    active: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Execution order when multiple triggers are defined.
+     * Lower numbers execute first.
+     */
+    order: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    object: string;
+    name: string;
+    active: boolean;
+    order: number;
+    action: "update" | "delete" | "insert" | ("update" | "delete" | "insert")[];
+    timing: "before" | "after";
+    execute: (args_0: {
+        user: Record<string, any>;
+        action: "update" | "delete" | "insert";
+        timing: "before" | "after";
+        doc: Record<string, any>;
+        userId: string;
+        addError: (args_0: string, args_1: string | undefined, ...args: unknown[]) => void;
+        getOldValue: (args_0: string, ...args: unknown[]) => any;
+        previousDoc?: Record<string, any> | undefined;
+        ql?: any;
+        logger?: any;
+    }, ...args: unknown[]) => Promise<void>;
+    description?: string | undefined;
+}, {
+    object: string;
+    name: string;
+    action: "update" | "delete" | "insert" | ("update" | "delete" | "insert")[];
+    timing: "before" | "after";
+    execute: (args_0: {
+        user: Record<string, any>;
+        action: "update" | "delete" | "insert";
+        timing: "before" | "after";
+        doc: Record<string, any>;
+        userId: string;
+        addError: (args_0: string, args_1: string | undefined, ...args: unknown[]) => void;
+        getOldValue: (args_0: string, ...args: unknown[]) => any;
+        previousDoc?: Record<string, any> | undefined;
+        ql?: any;
+        logger?: any;
+    }, ...args: unknown[]) => Promise<void>;
+    description?: string | undefined;
+    active?: boolean | undefined;
+    order?: number | undefined;
+}>;
+/**
+ * TypeScript types
+ */
+export type TriggerAction = z.infer<typeof TriggerAction>;
+export type TriggerTiming = z.infer<typeof TriggerTiming>;
+export type TriggerContext = z.infer<typeof TriggerContextSchema>;
+export type Trigger = z.infer<typeof TriggerSchema>;
+//# sourceMappingURL=trigger.zod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trigger.zod.d.ts","sourceRoot":"","sources":["../../src/data/trigger.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,aAAa,2CAAyC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,aAAa,gCAA8B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;OAGG;;IAGH;;;;OAIG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;OAOG;;IAGH;;OAEG;;IAGH;;;OAGG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;;;;OAWG;;IAMH;;;;;;;;;;;OAWG;;;;;;;;;;;;;;;;;;;;;;;;EAKH,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,aAAa;IACxB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;OAGG;;IAMH;;;OAGG;;QAnIH;;;WAGG;;QAGH;;;;WAIG;;QAGH;;;;;;WAMG;;QAGH;;;;;;;WAOG;;QAGH;;WAEG;;QAGH;;;WAGG;;QAGH;;;;;;;WAOG;;QAGH;;;;;;;WAOG;;QAGH;;;;;;;;;;;WAWG;;QAMH;;;;;;;;;;;WAWG;;;;;;;;;;;;;;;;;;;;;;;;;IA8CH;;OAEG;;IAGH;;OAEG;;IAGH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/data/trigger.zod.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TriggerSchema = exports.TriggerContextSchema = exports.TriggerTiming = exports.TriggerAction = void 0;
+const zod_1 = require("zod");
+/**
+ * Trigger Action Enum
+ *
+ * Defines the database operation that triggered the execution.
+ */
+exports.TriggerAction = zod_1.z.enum(['insert', 'update', 'delete']);
+/**
+ * Trigger Timing Enum
+ *
+ * Defines when the trigger executes relative to the database operation.
+ */
+exports.TriggerTiming = zod_1.z.enum(['before', 'after']);
+/**
+ * Trigger Context Schema
+ *
+ * This defines the runtime context available to trigger code during execution.
+ * Standardizes how trigger code is written and enables AI code generation.
+ *
+ * Triggers are business logic hooks that execute before or after database operations.
+ * They can validate data, set defaults, update related records, or prevent operations.
+ *
+ * @example Before Insert Trigger
+ * export default {
+ *   timing: 'before',
+ *   action: 'insert',
+ *   execute: async (context: TriggerContext) => {
+ *     // Set default values
+ *     if (!context.doc.status) {
+ *       context.doc.status = 'active';
+ *     }
+ *
+ *     // Validation
+ *     if (!context.doc.email) {
+ *       context.addError('Email is required');
+ *     }
+ *   }
+ * };
+ *
+ * @example After Update Trigger
+ * export default {
+ *   timing: 'after',
+ *   action: 'update',
+ *   execute: async (context: TriggerContext) => {
+ *     // Update related records
+ *     if (context.getOldValue('status') !== context.doc.status) {
+ *       await context.ql.object('activity_log').create({
+ *         record_id: context.doc.id,
+ *         message: `Status changed from ${context.getOldValue('status')} to ${context.doc.status}`,
+ *         user_id: context.userId,
+ *       });
+ *     }
+ *   }
+ * };
+ */
+exports.TriggerContextSchema = zod_1.z.object({
+    /**
+     * The database operation that triggered execution.
+     * One of: 'insert', 'update', 'delete'
+     */
+    action: exports.TriggerAction.describe('Database operation type'),
+    /**
+     * When the trigger executes relative to the operation.
+     * - 'before': Execute before database operation (can modify doc, prevent operation)
+     * - 'after': Execute after database operation (can trigger side effects)
+     */
+    timing: exports.TriggerTiming.describe('Trigger execution timing'),
+    /**
+     * The current document/record being operated on.
+     *
+     * For 'before' triggers: Can be modified to change what gets saved.
+     * For 'after' triggers: Contains the final saved state (read-only).
+     * For 'delete' triggers: Contains the record being deleted.
+     */
+    doc: zod_1.z.record(zod_1.z.any()).describe('Current document/record'),
+    /**
+     * The document state before the current operation.
+     *
+     * Only available for 'update' and 'delete' operations.
+     * Null for 'insert' operations.
+     *
+     * Use this to detect what changed in an update trigger.
+     */
+    previousDoc: zod_1.z.record(zod_1.z.any()).optional().describe('Previous document state'),
+    /**
+     * ID of the user performing the operation.
+     */
+    userId: zod_1.z.string().describe('Current user ID'),
+    /**
+     * Complete user record of the user performing the operation.
+     * Contains fields like name, email, roles, etc.
+     */
+    user: zod_1.z.record(zod_1.z.any()).describe('Current user record'),
+    /**
+     * ObjectQL data access API.
+     * Use this to query or modify other records.
+     *
+     * @example
+     * await context.ql.object('account').findOne(context.doc.account_id);
+     * await context.ql.object('activity').create({ ... });
+     */
+    ql: zod_1.z.any().describe('ObjectQL data access API'),
+    /**
+     * Logging interface.
+     * Use this for debugging and auditing.
+     *
+     * @example
+     * context.logger.info('Trigger executed', { recordId: context.doc.id });
+     * context.logger.error('Validation failed', { error });
+     */
+    logger: zod_1.z.any().describe('Logging interface'),
+    /**
+     * Add a validation error.
+     * For 'before' triggers only - prevents the operation from completing.
+     *
+     * @param message - Error message to display
+     * @param field - Optional field name the error relates to
+     *
+     * @example
+     * if (context.doc.amount < 0) {
+     *   context.addError('Amount must be positive', 'amount');
+     * }
+     */
+    addError: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.string().optional())
+        .returns(zod_1.z.void())
+        .describe('Add validation error'),
+    /**
+     * Get the old value of a field.
+     * Helper function for 'update' triggers to easily compare old vs new values.
+     *
+     * @param fieldName - Name of the field
+     * @returns Previous value of the field, or undefined if not available
+     *
+     * @example
+     * if (context.getOldValue('status') !== context.doc.status) {
+     *   // Status changed
+     * }
+     */
+    getOldValue: zod_1.z.function()
+        .args(zod_1.z.string())
+        .returns(zod_1.z.any())
+        .describe('Get previous field value'),
+});
+/**
+ * Trigger Definition Schema
+ *
+ * Complete definition of a trigger including metadata and execution function.
+ */
+exports.TriggerSchema = zod_1.z.object({
+    /**
+     * Unique trigger name.
+     */
+    name: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Trigger name (snake_case)'),
+    /**
+     * Object this trigger is attached to.
+     */
+    object: zod_1.z.string().describe('Target object name'),
+    /**
+     * Trigger timing.
+     */
+    timing: exports.TriggerTiming.describe('Execution timing'),
+    /**
+     * Trigger action(s).
+     * Can be a single action or array of actions.
+     */
+    action: zod_1.z.union([
+        exports.TriggerAction,
+        zod_1.z.array(exports.TriggerAction),
+    ]).describe('Database operation(s) to trigger on'),
+    /**
+     * Trigger execution function.
+     * Receives TriggerContext and performs the business logic.
+     */
+    execute: zod_1.z.function()
+        .args(exports.TriggerContextSchema)
+        .returns(zod_1.z.promise(zod_1.z.void()))
+        .describe('Trigger execution function'),
+    /**
+     * Optional description of what the trigger does.
+     */
+    description: zod_1.z.string().optional().describe('Trigger description'),
+    /**
+     * Whether the trigger is active.
+     */
+    active: zod_1.z.boolean().default(true).describe('Is trigger active'),
+    /**
+     * Execution order when multiple triggers are defined.
+     * Lower numbers execute first.
+     */
+    order: zod_1.z.number().default(0).describe('Execution order'),
+});