@objectstack/spec 0.1.1 → 0.1.2

package/dist/system/driver.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.zod.d.ts","sourceRoot":"","sources":["../../src/system/driver.zod.ts"],"names":[],"mappings":"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"}

package/dist/system/driver.zod.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriverInterfaceSchema = exports.DriverCapabilitiesSchema = exports.DriverOptionsSchema = void 0;
+const zod_1 = require("zod");
+const query_zod_1 = require("../data/query.zod");
+/**
+ * Common Driver Options
+ * Passed to most driver methods to control behavior (transactions, timeouts, etc.)
+ */
+exports.DriverOptionsSchema = zod_1.z.object({
+    /**
+     * Transaction handle/identifier.
+     * If provided, the operation must run within this transaction.
+     */
+    transaction: zod_1.z.any().optional().describe('Transaction handle'),
+    /**
+     * Operation timeout in milliseconds.
+     */
+    timeout: zod_1.z.number().optional().describe('Timeout in ms'),
+    /**
+     * Whether to bypass cache and force a fresh read.
+     */
+    skipCache: zod_1.z.boolean().optional().describe('Bypass cache'),
+});
+/**
+ * Driver Capabilities Schema
+ *
+ * Defines what features a database driver supports.
+ * This allows ObjectQL to adapt its behavior based on underlying database capabilities.
+ */
+exports.DriverCapabilitiesSchema = zod_1.z.object({
+    /**
+     * Whether the driver supports database transactions.
+     * If true, beginTransaction, commit, and rollback must be implemented.
+     */
+    transactions: zod_1.z.boolean().describe('Supports transactions'),
+    /**
+     * Whether the driver supports SQL-style joins.
+     * If false, ObjectQL will fetch related data separately and join in memory.
+     */
+    joins: zod_1.z.boolean().describe('Supports SQL joins'),
+    /**
+     * Whether the driver supports full-text search.
+     * If true, text search queries can be pushed to the database.
+     */
+    fullTextSearch: zod_1.z.boolean().describe('Supports full-text search'),
+    /**
+     * Whether the driver supports JSON field types.
+     * If false, JSON data will be serialized as strings.
+     */
+    jsonFields: zod_1.z.boolean().describe('Supports JSON field types'),
+    /**
+     * Whether the driver supports array field types.
+     * If false, arrays will be stored as JSON strings or in separate tables.
+     */
+    arrayFields: zod_1.z.boolean().describe('Supports array field types'),
+});
+/**
+ * Unified Database Driver Interface
+ *
+ * This is the contract that all storage adapters (Postgres, Mongo, Excel, Salesforce) must implement.
+ * It abstracts the underlying engine, enabling ObjectStack to be "Database Agnostic".
+ */
+exports.DriverInterfaceSchema = zod_1.z.object({
+    /**
+     * Driver name (e.g., 'postgresql', 'mongodb', 'rest_api').
+     */
+    name: zod_1.z.string().describe('Driver unique name'),
+    /**
+     * Driver version.
+     */
+    version: zod_1.z.string().describe('Driver version'),
+    /**
+     * Capabilities descriptor.
+     */
+    supports: exports.DriverCapabilitiesSchema,
+    // ============================================================================
+    // Lifecycle Management
+    // ============================================================================
+    /**
+     * Initialize connection pool or authenticate.
+     */
+    connect: zod_1.z.function()
+        .returns(zod_1.z.promise(zod_1.z.void()))
+        .describe('Establish connection'),
+    /**
+     * Close connections and cleanup resources.
+     */
+    disconnect: zod_1.z.function()
+        .returns(zod_1.z.promise(zod_1.z.void()))
+        .describe('Close connection'),
+    /**
+     * Check connection health.
+     * @returns true if healthy, false otherwise.
+     */
+    checkHealth: zod_1.z.function()
+        .returns(zod_1.z.promise(zod_1.z.boolean()))
+        .describe('Health check'),
+    // ============================================================================
+    // Raw Execution (Escape Hatch)
+    // ============================================================================
+    /**
+     * Execute a raw command/query native to the driver.
+     * Useful for complex reports, stored procedures, or DDL not covered by standard sync.
+     *
+     * @param command - The raw command (e.g., SQL string, shell command, or remote API payload).
+     * @param parameters - Optional array of bound parameters for safe execution (prevention of injection).
+     * @param options - Driver options (transaction context, timeout).
+     * @returns Promise resolving to the raw result from the driver.
+     *
+     * @example
+     * // SQL Driver
+     * await driver.execute('SELECT * FROM complex_view WHERE id = ?', [123]);
+     *
+     * // Mongo Driver
+     * await driver.execute({ aggregate: 'orders', pipeline: [...] });
+     */
+    execute: zod_1.z.function()
+        .args(zod_1.z.any(), zod_1.z.array(zod_1.z.any()).optional(), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.any()))
+        .describe('Execute raw command'),
+    // ============================================================================
+    // CRUD Operations
+    // ============================================================================
+    /**
+     * Find multiple records matching the structured query.
+     * Parsing the QueryAST is the responsibility of the driver implementation.
+     *
+     * @param object - The name of the object/table to query (e.g. 'account').
+     * @param query - The structured QueryAST (filters, sorts, joins, pagination).
+     * @param options - Driver options.
+     * @returns Array of records.
+     *
+     * @example
+     * await driver.find('account', {
+     *   filters: [['status', '=', 'active'], 'and', ['amount', '>', 500]],
+     *   sort: [{ field: 'created_at', order: 'desc' }],
+     *   top: 10
+     * });
+     */
+    find: zod_1.z.function()
+        .args(zod_1.z.string(), query_zod_1.QuerySchema, exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.array(zod_1.z.record(zod_1.z.any()))))
+        .describe('Find records'),
+    /**
+     * Find a single record by query.
+     * Similar to find(), but returns only the first match or null.
+     *
+     * @param object - The name of the object.
+     * @param query - QueryAST.
+     * @param options - Driver options.
+     */
+    findOne: zod_1.z.function()
+        .args(zod_1.z.string(), query_zod_1.QuerySchema, exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.record(zod_1.z.any()).nullable()))
+        .describe('Find one record'),
+    /**
+     * Create a new record.
+     *
+     * @param object - The object name.
+     * @param data - Key-value map of field data.
+     * @param options - Driver options.
+     * @returns The created record, including server-generated fields (id, created_at, etc.).
+     */
+    create: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.record(zod_1.z.any()), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.record(zod_1.z.any())))
+        .describe('Create record'),
+    /**
+     * Update an existing record by ID.
+     *
+     * @param object - The object name.
+     * @param id - The unique identifier of the record.
+     * @param data - The fields to update.
+     * @param options - Driver options.
+     * @returns The updated record.
+     */
+    update: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.string().or(zod_1.z.number()), zod_1.z.record(zod_1.z.any()), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.record(zod_1.z.any())))
+        .describe('Update record'),
+    /**
+     * Delete a record by ID.
+     *
+     * @param object - The object name.
+     * @param id - The unique identifier of the record.
+     * @param options - Driver options.
+     * @returns True if deleted, false if not found.
+     */
+    delete: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.string().or(zod_1.z.number()), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.boolean()))
+        .describe('Delete record'),
+    /**
+     * Count records matching a query.
+     *
+     * @param object - The object name.
+     * @param query - Optional filtering criteria.
+     * @param options - Driver options.
+     * @returns Total count.
+     */
+    count: zod_1.z.function()
+        .args(zod_1.z.string(), query_zod_1.QuerySchema.optional(), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.number()))
+        .describe('Count records'),
+    // ============================================================================
+    // Bulk Operations
+    // ============================================================================
+    /**
+     * Create multiple records in a single batch.
+     * Optimized for performance.
+     *
+     * @param object - The object name.
+     * @param dataArray - Array of record data.
+     * @returns Array of created records.
+     */
+    bulkCreate: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.array(zod_1.z.record(zod_1.z.any())), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.array(zod_1.z.record(zod_1.z.any())))),
+    /**
+     * Update multiple records in a single batch.
+     *
+     * @param object - The object name.
+     * @param updates - Array of objects containing {id, data}.
+     * @returns Array of updated records.
+     */
+    bulkUpdate: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.array(zod_1.z.object({ id: zod_1.z.string().or(zod_1.z.number()), data: zod_1.z.record(zod_1.z.any()) })), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.array(zod_1.z.record(zod_1.z.any())))),
+    /**
+     * Delete multiple records in a single batch.
+     *
+     * @param object - The object name.
+     * @param ids - Array of record IDs.
+     */
+    bulkDelete: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.array(zod_1.z.string().or(zod_1.z.number())), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.void())),
+    // ============================================================================
+    // Transaction Management
+    // ============================================================================
+    /**
+     * Begin a new database transaction.
+     * @returns A transaction handle to be passed to subsequent operations via `options.transaction`.
+     */
+    beginTransaction: zod_1.z.function()
+        .returns(zod_1.z.promise(zod_1.z.any()))
+        .describe('Start transaction'),
+    /**
+     * Commit the transaction.
+     * @param transaction - The transaction handle.
+     */
+    commit: zod_1.z.function()
+        .args(zod_1.z.any())
+        .returns(zod_1.z.promise(zod_1.z.void()))
+        .describe('Commit transaction'),
+    /**
+     * Rollback the transaction.
+     * @param transaction - The transaction handle.
+     */
+    rollback: zod_1.z.function()
+        .args(zod_1.z.any())
+        .returns(zod_1.z.promise(zod_1.z.void()))
+        .describe('Rollback transaction'),
+    // ============================================================================
+    // Schema Management
+    // ============================================================================
+    /**
+     * Synchronize the database schema with the Object definition.
+     * This is an idempotent operation: it should create tables if missing,
+     * add columns if missing, and update indexes.
+     *
+     * @param object - The object name.
+     * @param schema - The full Object Schema (fields, indexes, etc).
+     * @param options - Driver options.
+     */
+    syncSchema: zod_1.z.function()
+        .args(zod_1.z.string(), zod_1.z.any(), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.void()))
+        .describe('Sync object schema to DB'),
+    /**
+     * Drop the underlying table or collection for an object.
+     * WARNING: Destructive operation.
+     *
+     * @param object - The object name.
+     */
+    dropTable: zod_1.z.function()
+        .args(zod_1.z.string(), exports.DriverOptionsSchema.optional())
+        .returns(zod_1.z.promise(zod_1.z.void())),
+});

package/dist/system/license.zod.d.ts

@@ -90,19 +90,19 @@ export declare const LicenseSchema: z.ZodObject<{
     tenantId: string;
     planCode: string;
     issuedAt: string;
+    signature?: string | undefined;
     expiresAt?: string | undefined;
     customFeatures?: string[] | undefined;
     customLimits?: Record<string, number> | undefined;
-    signature?: string | undefined;
 }, {
     status: "active" | "expired" | "suspended" | "trial";
     tenantId: string;
     planCode: string;
     issuedAt: string;
+    signature?: string | undefined;
     expiresAt?: string | undefined;
     customFeatures?: string[] | undefined;
     customLimits?: Record<string, number> | undefined;
-    signature?: string | undefined;
 }>;
 export type Feature = z.infer<typeof FeatureSchema>;
 export type Plan = z.infer<typeof PlanSchema>;