@asaidimu/anansi 1.6.6 → 2.0.0

package/index.d.ts

@@ -1,6 +1,6 @@
 import * as _faker_js_faker from '@faker-js/faker';
 import { Faker } from '@faker-js/faker';
-import { QueryDSL, QueryFilter } from '@asaidimu/query';
+import { LogicalOperator, QueryDSL, QueryFilter } from '@asaidimu/query';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import LightningFS from '@isomorphic-git/lightning-fs';
 import { FieldValues, ResolverOptions, ResolverResult } from 'react-hook-form';
@@ -172,10 +172,6 @@ type SchemaHint = {
     groups?: GroupDefinition[];
 };
 
-/**
- * Logical operators for combining constraints or index conditions.
- */
-type LogicalOperator = "and" | "or" | "not" | "nor" | "xor";
 /**
  * Basic field types supported by the schema system.
  */
@@ -415,73 +411,195 @@ interface IndexDefinition {
     name: string;
 }
 /**
- * Represents a nested schema definition embedded within a parent schema.
- * Unlike SchemaDefinition, this can use a discriminated array of field sets for variant-specific fields,
- * but only when concrete is false. This restriction avoids complexity in RDBMS implementations,
- * where concrete schemas map directly to tables with fixed columns. Non-concrete schemas, as embedded
- * structures, can leverage this flexibility without affecting physical table design.
+ * Defines a reusable nested schema structure.
+ * This can represent either a complex object with defined fields, or a direct primitive literal (string, number, boolean).
+ * Nested schemas are stored in the `nestedSchemas` map of a `SchemaDefinition` and referenced by their `id`.
+ * They facilitate schema reusability, modularity, and the definition of polymorphic structures.
+ *
+ * @template T - The TypeScript type this schema represents. When `literal` is `true`, this `T`
+ * corresponds to the actual primitive type (e.g., `string`, `number`).
+ * When `literal` is `false`, `T` is typically an object type.
  *
  * @example
+ * // Example of a concrete, object-based nested schema (like a fixed address structure)
  * ```typescript
  * const addressSchema: NestedSchemaDefinition = {
- *    name: "address",
- *    fields: {
- *        street: { name: "street", type: "string" },
- *        city: { name: "city", type: "string" },
- *        zip: { name: "zip", type: "string" }
- *    },
- *    concrete: true
+ * name: "AddressSchema",
+ * description: "A concrete schema for geographical addresses.",
+ * fields: {
+ * street: { name: "street", type: "string", description: "Street name and number." },
+ * city: { name: "city", type: "string", description: "City or town." },
+ * zip: { name: "zip", type: "string", description: "Postal or zip code." }
+ * },
+ * concrete: true // Suitable for RDBMS table mapping
  * };
+ * ```
  *
+ * @example
+ * // Example of a non-concrete, object-based nested schema with discriminated fields (like a contact method)
+ * ```typescript
  * const contactSchema: NestedSchemaDefinition = {
- *    name: "contact",
- *    fields: [
- *        { fields: { email: { name: "email", type: "string" } }, when: { field: "type", value: "email" } },
- *        { fields: { phone: { name: "phone", type: "string" } }, when: { field: "type", value: "phone" } }
- *    ]
+ * name: "ContactMethod",
+ * description: "Represents various contact methods using a discriminated union.",
+ * fields: [
+ * {
+ * fields: {
+ * type: { name: "type", type: "enum", values: ["email"], required: true },
+ * email: { name: "email", type: "string", hint: { input: { type: "email" } } }
+ * },
+ * when: { field: "type", value: "email" }
+ * },
+ * {
+ * fields: {
+ * type: { name: "type", type: "enum", values: ["phone"], required: true },
+ * phone: { name: "phone", type: "string", hint: { input: { type: "tel" } } }
+ * },
+ * when: { field: "type", value: "phone" }
+ * }
+ * ],
+ * concrete: false // Allows for discriminated field sets
+ * };
+ * ```
+ *
+ * @example
+ * // Example of a literal nested schema (reusable email string definition)
+ * ```typescript
+ * const emailStringSchema: NestedSchemaDefinition<string> = {
+ * name: "EmailAddressString",
+ * description: "A literal schema for a validated email address string.",
+ * literal: true,
+ * type: "string",
+ * constraints: {
+ * predicates: {
+ * matches: "/^[^\s@]+@[^\s@]+\\.[^\s@]+$/" // Regex for email format validation
+ * }
+ * }
  * };
  * ```
  */
-interface NestedSchemaDefinition {
+type NestedSchemaDefinition<T> = {
     /**
-     * The name of the nested schema, unique within the parent schema's nestedSchemas.
+     * The unique name or identifier of the nested schema within the parent schema's `nestedSchemas` map.
+     * This `name` is used by `FieldDefinition.schema.id` to reference this nested schema.
+     * @example "AddressSchema" or "EmailString"
      */
     name: string;
     /**
-     * A description of the nested schema's purpose.
+     * A clear and concise description of the nested schema's purpose, structure, or expected data.
+     * This is crucial for documentation and understanding the schema's intent.
      */
     description?: string;
+} & (
+/**
+ * Defines a literal nested schema.
+ * When `literal` is `true`, this `NestedSchemaDefinition` represents a direct primitive value
+ * (string, number, or boolean) rather than an object with fields.
+ * This is particularly useful for:
+ * - Defining reusable primitive types with specific constraints (e.g., a regex for an "EmailAddress" string).
+ * - Enabling direct unions between primitive types and object types within a `FieldDefinition`
+ * (e.g., `FieldType: "union"`, where one `FieldSchema` references a literal type).
+ */
+{
+    literal: true;
+    /**
+     * The basic primitive type that this literal schema represents.
+     * Must be one of "string", "number", or "boolean".
+     */
+    type: "string" | "number" | "boolean";
+    /**
+     * An optional default value for this literal schema.
+     * If provided, the type of `default` must strictly match the `type` specified.
+     * @example "default@example.com" for type "string"
+     * @example 0 for type "number"
+     */
+    default?: T;
+    /**
+     * Optional constraints for additional validation rules specific to this literal type.
+     * These constraints apply directly to the primitive value.
+     */
+    constraints?: Array<Constraint<any> | ConstraintGroup<any>>;
+    /**
+     * Optional generic metadata associated with the literal schema.
+     * This can store any additional information relevant to tooling or specific domain requirements.
+     * @example `{ uiComponent: "emailInput", validationMessage: "Invalid email format" }`
+     */
+    metadata?: Record<string, any>;
+} | 
+/**
+ * Defines a structured nested schema that represents an object with defined fields.
+ * This is the traditional way of defining complex data structures within the schema.
+ */
+{
     /**
-     * Indicates whether this schema represents a standalone entity (true) or is embedded (false).
-     * When true, fields must be a Record<string, FieldDefinition<any>> to ensure a fixed structure
-     * suitable for RDBMS table mapping. When false, fields can be an array of discriminated field sets.
+     * Explicitly indicates that this is a non-literal, structured schema.
+     * Default value is `false` if omitted.
+     */
+    literal?: false;
+    /**
+     * Indicates whether this schema represents a standalone entity (`true`) or is embedded (`false`).
+     * - When `true` (`concrete: true`), the schema is treated as a distinct, fixed-structure entity,
+     * often suitable for direct mapping to RDBMS tables. In this case, `fields` *must* be a
+     * `Record<string, FieldDefinition<any>>` to ensure a consistent, non-polymorphic structure.
+     * - When `false` (`concrete: false` or omitted), the schema is considered embedded or polymorphic.
+     * `fields` can be either a `Record<string, FieldDefinition<any>>` (for a fixed embedded object)
+     * or an `Array<{ fields: Record<string, FieldDefinition<any>>; when?: { field: string; value: any } }>`,
+     * allowing discriminated field sets based on a specific field's value (e.g., a 'type' field).
+     * The array form enables defining variants within a single schema without imposing strict concrete
+     * constraints, but is not supported for `concrete: true` schemas to maintain simplicity in RDBMS table mappings.
      * @default false
      */
     concrete?: boolean;
     /**
-     * Defines the fields of the nested schema.
-     * - If concrete is true, must be a Record<string, FieldDefinition<any>> for a fixed field set.
-     * - If concrete is false, can be either a Record<string, FieldDefinition<any>> or an
-     * Array<{ fields: Record<string, FieldDefinition<any>>; when?: { field: string; value: any } }>,
-     * allowing discriminated field sets based on a field value (e.g., 'type').
-     * The array form enables variant-specific fields without constraints, but is not supported for
-     * concrete schemas to maintain simplicity in RDBMS table mappings.
+     * Defines the fields (properties) that constitute this nested schema.
+     * The structure of `fields` depends on the `concrete` property:
+     * - If `concrete` is `true`, `fields` must be a `Record<string, FieldDefinition<any>>`
+     * to define a fixed set of named fields (e.g., for a database table).
+     * - If `concrete` is `false` (or omitted), `fields` can be:
+     * - A `Record<string, FieldDefinition<any>>` for a simple, embedded object.
+     * - An `Array<{ fields: Record<string, FieldDefinition<any>>; when?: { field: string; value: any } }>`
+     * to define a discriminated union or polymorphic structure. Each object in the array defines a
+     * set of fields that apply `when` a specified `field` (within this schema's own fields)
+     * has a particular `value`. This allows for variant-specific fields.
      */
     fields: Record<string, FieldDefinition<any>> | Array<{
+        /**
+         * A set of field definitions that apply when the `when` condition is met.
+         */
         fields: Record<string, FieldDefinition<any>>;
+        /**
+         * An optional condition that makes this set of fields active.
+         * This object specifies a `field` (its name within this schema) and a `value`.
+         * When the specified `field` in the data matches this `value`, these `fields` are considered active.
+         * Used for discriminated unions or polymorphic structures (e.g., `when: { field: "type", value: "car" }`).
+         * If `when` is omitted for an entry in the array, those fields are always present in the union's base,
+         * or it acts as a fallback if no other `when` condition matches.
+         */
         when?: {
             field: string;
             value: any;
         };
     }>;
     /**
-     * Optional constraints for additional validation rules.
-     * Less necessary when using discriminated field sets, as variant logic can be structural.
+     * Optional constraints for additional validation rules that apply to the entire structured schema.
+     * These constraints provide an extra layer of data integrity beyond basic type checking.
+     * They are less strictly necessary when using discriminated field sets (`fields` as an array),
+     * as much of the variant logic can be enforced structurally through the `when` clauses.
      */
     constraints?: SchemaConstraint<any>;
+    /**
+     * Defines database indexes for the fields within this nested schema.
+     * This is primarily applicable when `concrete` is `true`, indicating that the schema
+     * maps directly to a persistent data store table. Indexes help optimize data retrieval.
+     */
     indexes?: IndexDefinition[];
+    /**
+     * Optional generic metadata associated with the structured schema.
+     * This can store any additional information relevant to tooling, UI generation,
+     * or specific domain requirements that are not covered by other properties.
+     * @example `{ graphqlType: "Address", apiEndpoint: "/api/addresses" }`
+     */
     metadata?: Record<string, any>;
-}
+});
 /**
  * Defines a complete schema, intended as an atomic unit within a larger domain model.
  *
@@ -519,7 +637,7 @@ interface SchemaDefinition {
     description?: string;
     fields: Record<string, FieldDefinition<any>>;
     /** Reusable nested schema definitions, now as mini-SchemaDefinitions. */
-    nestedSchemas: Record<string, NestedSchemaDefinition>;
+    nestedSchemas?: Record<string, NestedSchemaDefinition<any>>;
     indexes?: IndexDefinition[];
     constraints?: SchemaConstraint<any>;
     metadata?: Record<string, any>;
@@ -598,14 +716,14 @@ type SchemaChange<T> = {
 } | {
     type: "addNestedSchema";
     id: string;
-    definition: NestedSchemaDefinition;
+    definition: NestedSchemaDefinition<any>;
 } | {
     type: "removeNestedSchema";
     id: string;
 } | {
     type: "modifyNestedSchema";
     id: string;
-    changes: Partial<NestedSchemaDefinition>;
+    changes: Partial<NestedSchemaDefinition<any>>;
 };
 /**
  * Defines a transform function for data migration between schema versions.
@@ -962,7 +1080,7 @@ interface SchemaMigrationHelper {
      * @param {string} schemaId - The ID of the nested schema to add.
      * @param {NestedSchemaDefinition} nestedDefinition - The definition of the nested schema to add.
      */
-    addNestedSchema(schemaId: string, nestedDefinition: NestedSchemaDefinition): void;
+    addNestedSchema(schemaId: string, nestedDefinition: NestedSchemaDefinition<any>): void;
     /**
      * Removes a nested schema from the schema.
      * @param {string} schemaId - The ID of the nested schema to remove.
@@ -973,7 +1091,7 @@ interface SchemaMigrationHelper {
      * @param {string} schemaId - The ID of the nested schema to modify.
      * @param {Partial<NestedSchemaDefinition>} changes - The changes to apply to the nested schema.
      */
-    modifyNestedSchema(schemaId: string, changes: Partial<NestedSchemaDefinition>): void;
+    modifyNestedSchema(schemaId: string, changes: Partial<NestedSchemaDefinition<any>>): void;
     /**
      * Returns the list of changes made through this helper.
      * @returns An array of schema changes.
@@ -984,185 +1102,635 @@ interface SchemaMigrationHelper {
     };
 }
 
+/**
+ * Defines the possible event types for persistence operations.
+ */
+type PersistenceEventType = "create:start" | "create:success" | "create:failed" | "read:start" | "read:success" | "read:failed" | "migrate:start" | "migrate:success" | "migrate:failed" | "rollback:start" | "rollback:success" | "rollback:failed" | "update:start" | "update:success" | "update:failed" | "delete:start" | "delete:success" | "delete:failed" | "transaction:start" | "transaction:success" | "transaction:failed" | "telemetry" | "collection:create:start" | "collection:create:success" | "collection:create:failed" | "collection:delete:start" | "collection:delete:success" | "collection:delete:failed" | "subscription:register" | "subscription:unregister" | "trigger:register" | "trigger:unregister" | "trigger:execute" | "trigger:failed" | "task:register" | "task:unregister" | "task:start" | "task:success" | "task:failed" | "metadata:called";
+/**
+ * Interface representing events emitted during persistence operations.
+ */
+interface PersistenceEvent<DataType> {
+    /** The type of event (e.g., 'create:start', 'trigger:execute'). */
+    type: PersistenceEventType;
+    /** Timestamp when the event occurred. */
+    timestamp: number;
+    /** The operation being performed (e.g., 'create', 'trigger'). */
+    operation: string;
+    /** Name of the collection affected by the operation (if applicable). */
+    collection?: string;
+    /** Data passed to the operation (if applicable). */
+    input?: any;
+    /** Data returned by the operation (if applicable). */
+    output?: any;
+    /** Error object if the operation failed (if applicable). */
+    error?: Error;
+    /** Issues that caused the operation to fail (if applicable). */
+    issues?: Array<StandardSchemaV1.Issue>;
+    /** Query used in the operation (if applicable). */
+    query?: QueryDSL<DataType, any>;
+    /** Identifier for the transaction (if part of one). */
+    transactionId?: string;
+    /** Duration of the operation in milliseconds. */
+    duration?: number;
+    /** Additional context or metadata specific to the operation. */
+    context?: Record<string, any>;
+}
+/**
+ * Describes a subscription configuration.
+ */
+interface SubscriptionInfo {
+    /** The event subscribed to. */
+    event: PersistenceEventType;
+    /** Unique identifier for the callback. */
+    callbackId: string;
+    /** Optional short identifier (max 50 chars, unique within scope). */
+    label?: string;
+    /** Optional description of the subscription's purpose (max 500 chars). */
+    description?: string;
+}
+/**
+ * Describes a trigger configuration.
+ */
+interface TriggerInfo<T, FunctionMap = Record<string, any>> {
+    /** The event(s) or pattern triggering the callback. */
+    event: PersistenceEventType | PersistenceEventType[] | `${string}:*`;
+    /** Optional condition for the trigger. */
+    condition?: QueryFilter<T, FunctionMap>;
+    /** Unique identifier for the callback. */
+    callbackId: string;
+    /** Whether the trigger executes synchronously. */
+    isSync: boolean;
+    /** Short identifier (max 50 chars, unique within scope). */
+    label: string;
+    /** Description of the trigger's purpose (max 500 chars). */
+    description: string;
+}
+/**
+ * Describes a scheduled task configuration.
+ */
+interface TaskInfo {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Schedule for task execution. */
+    schedule: TaskSchedule;
+    /** Unique identifier for the callback. */
+    callbackId: string;
+    /** Whether the task executes synchronously. */
+    isSync: boolean;
+    /** Optional metadata for logging or telemetry. */
+    metadata?: Record<string, any>;
+    /** Short identifier (max 50 chars, unique within scope). */
+    label: string;
+    /** Description of the task's purpose (max 500 chars). */
+    description: string;
+}
+/**
+ * Filter criteria for metadata queries.
+ */
+interface MetadataFilter {
+    /** Filter for subscriptions. */
+    subscriptions?: {
+        event?: PersistenceEventType | PersistenceEventType[];
+        label?: string;
+    };
+    /** Filter for triggers. */
+    triggers?: {
+        event?: PersistenceEventType | PersistenceEventType[] | `${string}:*`;
+        label?: string;
+    };
+    /** Filter for tasks. */
+    tasks?: {
+        id?: string;
+        metadata?: Record<string, any>;
+        label?: string;
+    };
+    /** Filter for schemas. */
+    schemas?: {
+        id?: string;
+    };
+}
+/**
+ * Metadata for a single collection.
+ */
+interface CollectionMetadata<T, FunctionMap = Record<string, any>> {
+    /** Collection identifier. */
+    id: string;
+    /** Active subscriptions for the collection. */
+    subscriptions: SubscriptionInfo[];
+    /** Active triggers for the collection. */
+    triggers: TriggerInfo<T, FunctionMap>[];
+    /** Scheduled tasks for the collection. */
+    tasks: TaskInfo[];
+    /** Number of records in the collection. */
+    recordCount: number;
+    /** Storage used by the collection in bytes. */
+    dataSizeBytes: number;
+    /** Schema definition for the collection. */
+    schema: SchemaDefinition;
+    /** Timestamp of the last operation on the collection. */
+    lastModified: number;
+}
+/**
+ * Metadata for Persistence or PersistenceCollection.
+ */
+interface Metadata<T, FunctionMap = Record<string, any>> {
+    /** Active subscriptions. */
+    subscriptions: SubscriptionInfo[];
+    /** Active triggers. */
+    triggers: TriggerInfo<T, FunctionMap>[];
+    /** Scheduled tasks. */
+    tasks: TaskInfo[];
+    /** Number of collections (Persistence only). */
+    collectionCount?: number;
+    /** Total storage used by all collections in bytes (Persistence only). */
+    storageUsageBytes?: number;
+    /** Database connection status (Persistence only). */
+    connectionStatus?: "connected" | "disconnected" | "error";
+    /** Database connection error, if any (Persistence only). */
+    connectionError?: string | null;
+    /** Schema definitions for all collections, if requested (Persistence only). */
+    schemas?: SchemaDefinition[];
+    /** Per-collection metadata, if requested (Persistence only). */
+    collections?: CollectionMetadata<any, FunctionMap>[];
+    /** Number of records in the collection (PersistenceCollection only). */
+    recordCount?: number;
+    /** Storage used by the collection in bytes (PersistenceCollection only). */
+    dataSizeBytes?: number;
+    /** Schema definition for the collection (PersistenceCollection only). */
+    schema?: SchemaDefinition;
+    /** Timestamp of the last operation on the collection (PersistenceCollection only). */
+    lastModified?: number;
+}
+/**
+ * Interface for querying observability data.
+ */
+interface ObservabilityInterface<T, FunctionMap = Record<string, any>> {
+    /**
+     * Returns metadata about active subscriptions, triggers, tasks, and system state.
+     * @param filter Optional filter to limit returned data (e.g., by event or label).
+     * @param includeCollections For Persistence, whether to include per-collection metadata.
+     * @param includeSchemas For Persistence, whether to include schema definitions.
+     * @param forceRefresh Whether to force real-time queries for storageUsageBytes and dataSizeBytes.
+     * @returns Metadata object containing observability data.
+     * @example
+     * // Collection metadata with label filter
+     * const metadata = collection.metadata({ triggers: { label: "user-*" } });
+     * console.log(metadata.triggers); // Triggers with label "user-*"
+     * console.log(metadata.dataSizeBytes); // Storage used
+     *
+     * // Persistence metadata
+     * const globalMetadata = persistence.metadata({ includeCollections: true });
+     * console.log(globalMetadata.storageUsageBytes); // Total storage
+     * console.log(globalMetadata.collections); // Per-collection metadata
+     */
+    metadata(filter?: MetadataFilter, includeCollections?: boolean, includeSchemas?: boolean, forceRefresh?: boolean): Metadata<T, FunctionMap>;
+}
+/**
+ * Interface for event handling and task scheduling.
+ */
+interface EventTaskInterface<T, FunctionMap = Record<string, any>> {
+    /**
+     * Subscribes to persistence events.
+     * @param event The event to subscribe to.
+     * @param callback The callback to handle the event.
+     * @param options Optional label and description for the subscription.
+     * @returns A function to unsubscribe from the event.
+     * @example
+     * const unsubscribe = persistence.subscribe("telemetry", (event) => {
+     *   console.log(event);
+     * }, { label: "telemetry-log", description: "Logs telemetry events" });
+     * unsubscribe();
+     */
+    subscribe(event: PersistenceEventType, callback: (payload: PersistenceEvent<T>) => void, options?: {
+        label?: string;
+        description?: string;
+    }): () => void;
+    /**
+     * Registers a trigger callback for specific events.
+     * @param config Configuration including event, callback, label, description, and options.
+     * @returns A function to unsubscribe the trigger.
+     * @example
+     * collection.trigger("create:success",
+     *   ({ collection, results }) => {
+     *     console.log(`Created: ${results.id}`);
+     *   },
+     *   {
+     *    label: "user-create-hook",
+     *    description: "Syncs new users with CRM",
+     *    sync: true
+     * });
+     */
+    trigger(event: PersistenceEventType | PersistenceEventType[] | `${string}:*`, callback: (context: TriggerContext<T, FunctionMap>) => void | Promise<void>, options: {
+        condition?: QueryFilter<T, FunctionMap>;
+        sync?: boolean;
+        label: string;
+        description: string;
+    }): () => void;
+    /**
+     * Schedules a task to run at specified times or intervals.
+     * @param config Configuration including ID, schedule, callback, label, description, and options.
+     * @returns A function to cancel the scheduled task.
+     * @example
+     * collection.schedule({
+     *   id: "cleanup-inactive",
+     *   label: "inactive-cleanup",
+     *   description: "Deletes inactive records hourly",
+     *   schedule: { cron: "0 * * * *" },
+     *   callback: ({ collection }) => {
+     *     collection.delete({ query: { filter: { status: { $eq: "inactive" } } } });
+     *   }
+     * });
+     */
+    schedule(config: {
+        id: string;
+        schedule: TaskSchedule;
+        callback: (context: TaskContext<T, FunctionMap>) => void | Promise<void>;
+        sync?: boolean;
+        metadata?: Record<string, any>;
+        label: string;
+        description: string;
+    }): () => void;
+}
 /**
  * Interface defining persistence operations for data management.
- * Provides methods for CRUD operations, transactions, validation, and event subscription.
- *
- * @generic DataType - The type of data being persisted.
- * @generic FunctionMap - A map of functions used in the persistence operations (default: Record<string, any>).
  */
-interface Persistence<FunctionMap> {
+interface Persistence<FunctionMap = Record<string, any>> extends ObservabilityInterface<any, FunctionMap>, EventTaskInterface<any, FunctionMap> {
     /**
-     * Returns a list of all collections
-     * @returns A promise that resolves to a list of collection names
+     * Returns a list of all collection names.
+     * @returns A promise that resolves to an array of collection names.
      */
     collections(): Promise<Array<string>>;
     /**
      * Creates a new collection with the specified schema.
-     * @param schema - The schema definition for the new collection.
-     * @returns A promise that resolves when the collection is created.
+     * @param schema The schema definition for the new collection.
+     * @returns A promise that resolves to the created PersistenceCollection.
      */
-    createCollection<T>(schema: SchemaDefinition): Promise<PersistenceCollection<T, FunctionMap>>;
+    create<T>(schema: SchemaDefinition): Promise<PersistenceCollection<T, FunctionMap>>;
     /**
      * Deletes the specified collection.
-     * @param id - The ID of the collection to delete.
-     * @returns A promise that resolves when the collection is deleted.
+     * @param id The ID of the collection to delete.
+     * @returns A promise that resolves indicating whether the collection was deleted.
      */
-    deleteCollection(id: string): Promise<void>;
+    delete(id: string): Promise<boolean>;
     /**
      * Retrieves the schema definition for the specified collection.
-     * @param id - The ID of the collection.
-     * @returns A promise that resolves to the schema definition of the collection.
+     * @param id The ID of the collection.
+     * @returns A promise that resolves to the schema definition.
      */
     schema(id: string): Promise<SchemaDefinition>;
     /**
-     * Returns an object that can be used to interact with a collection of data
-     *
+     * Returns a PersistenceCollection instance for interacting with a collection.
+     * @param id The ID of the collection.
+     * @returns The PersistenceCollection instance.
      */
     collection<T>(id: string): PersistenceCollection<T, FunctionMap>;
-    /**
-     * Subscribe to persistence events
-     * @param event - The event to subscribe to
-     * @param callback - A callback to handle the event
-     * @returns A callback that can be used to unsubscribe from the event
-     */
-    subscribe(event: PersistenceEventType, callback: (payload: PersistenceEvent<any>) => void): () => void;
     /**
      * Executes a transaction with multiple operations.
-     * @param callback A function that receives a PersistenceTransaction object to perform multiple operations.
-     * @param callback.tx The PersistenceTransaction object used to perform transactional operations.
-     * @returns A promise that resolves to the result of the transaction.
+     * @param callback A function that receives a PersistenceTransaction object.
+     * @returns A promise that resolves to the transaction result.
      */
     transact<ReturnType>(callback: (tx: PersistenceTransaction<FunctionMap>) => Promise<ReturnType>): Promise<ReturnType>;
 }
-type PersistenceTransaction<F> = Omit<Persistence<F>, "subscribe" | "transact">;
-interface PersistenceCollection<T, FunctionMap> {
+/**
+ * Transaction interface, omitting subscribe, trigger, schedule, and transact methods.
+ */
+type PersistenceTransaction<F> = Omit<Persistence<F>, "subscribe" | "trigger" | "schedule" | "transact">;
+/**
+ * Interface for managing a single collection's data operations.
+ */
+interface PersistenceCollection<T, FunctionMap = Record<string, any>> extends ObservabilityInterface<T, FunctionMap>, EventTaskInterface<T, FunctionMap> {
     /**
-     * Creates a new record or multiple records in the specified collection.
-     * @param params An object containing the data to create and the collection name.
-     * @param params.data The data to be inserted; can be a single record or an array of records.
-     * @param params.collection The name of the collection to create records in.
-     * @returns A promise that resolves to the created record(s) with their generated IDs.
+     * Creates a new record or multiple records in the collection.
+     * @param params The data to create.
+     * @returns A promise that resolves to the created record(s).
      */
     create(params: {
         data: T | T[];
     }): Promise<T | T[]>;
     /**
-     * Retrieves one or more records from the specified collection.
-     * @param params An object containing the query and collection name.
-     * @param params.query The query defining the filter, sort, pagination, and projection options.
-     * @returns A promise that resolves to a single record or an array of matching records.
+     * Retrieves one or more records from the collection.
+     * @param params The query defining the filter, sort, pagination, and projection.
+     * @returns A promise that resolves to the matching record or array of records.
      */
     read(params: {
         query: QueryDSL<T, FunctionMap>;
-    }): Promise<T | T[]>;
+    }): Promise<T | Array<T>>;
     /**
-     * Updates one or more records in the specified collection.
-     * @param params An object containing the updated data, query, and collection name.
-     * @param params.data The updated data to be applied; can be a single partial record or an array of partial records.
-     * @param params.query The query defining which records to update.
+     * Updates one or more records in the collection.
+     * @param params The updated data, patch, or query.
      * @returns A promise that resolves to the updated records.
      */
     update(params: {
         data?: Partial<T>;
         patch?: PatchOperation | Array<PatchOperation>;
-        query: QueryFilter<T, any>;
+        query: QueryFilter<T, FunctionMap>;
     }): Promise<Array<T>>;
     /**
-     * Deletes one or more records from the specified collection.
-     * @param params An object containing either the query or records to delete, and the collection name.
-     * @param params.query The query defining which records to delete.
-     * @param params.records An array of records to delete.
-     * @returns A promise that resolves to the number of deleted records or the deleted records themselves.
+     * Deletes one or more records from the collection.
+     * @param params The query defining which records to delete.
+     * @returns A promise that resolves to the number of deleted records.
      */
     delete(params: {
-        query: QueryFilter<T, any>;
+        query: QueryFilter<T, FunctionMap>;
     }): Promise<number>;
     /**
-     * Validates an object against a schema.
-     * @param params An object containing the data, and collection name.
-     * @param params.data The object to validate.
-     * @returns An object containing validation results.
+     * Validates an object against the collection's schema.
+     * @param data The object to validate.
+     * @returns Validation results.
      */
     validate(data: any): {
         valid: boolean;
         issues: ReadonlyArray<StandardSchemaV1.Issue> | null;
     };
     /**
-     * Subscribe to persistence events
-     * @param event - The event to subscribe to
-     * @param callback - A callback to handle the event
-     * @returns A callback that can be used to unsubscribe from the event
+     * Rolls back the collection to a previous schema version.
+     * @param version The version to roll back to (optional).
+     * @param dryRun Whether to simulate the rollback.
+     * @returns A promise that resolves to the new schema and data preview, or undefined.
      */
-    subscribe(event: PersistenceEventType, callback: (payload: PersistenceEvent<T>) => void): () => void;
     rollback(version?: string, dryRun?: boolean): Promise<{
-        newSchema: SchemaDefinition;
-        dataPreview: ReadableStream<any>;
+        schema: SchemaDefinition;
+        preview: ReadableStream<any>;
     } | undefined>;
+    /**
+     * Applies a schema migration to the collection.
+     * @param description A description of the migration.
+     * @param cb A callback defining the transformation logic.
+     * @param dryRun Whether to simulate the migration.
+     * @returns A promise that resolves to the new schema and data preview, or undefined.
+     */
     migrate(description: string, cb: (h: Omit<SchemaMigrationHelper, "changes">) => DataTransform<any, any> | undefined, dryRun?: boolean): Promise<{
-        newSchema: SchemaDefinition;
-        dataPreview: ReadableStream<any>;
+        schema: SchemaDefinition;
+        preview: ReadableStream<any>;
     } | undefined>;
 }
 /**
- * Defines the possible event types for persistence operations
+ * Context for collection-specific triggers.
+ */
+type CollectionTriggerContext<T, FunctionMap = Record<string, any>> = {
+    event: PersistenceEvent<T> & {
+        type: "create:start";
+        operation: "create";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        data: T | T[];
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "create:success";
+        operation: "create";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        data: T | T[];
+    };
+    results: T | T[];
+} | {
+    event: PersistenceEvent<T> & {
+        type: "create:failed";
+        operation: "create";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        data: T | T[];
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "read:start";
+        operation: "read";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        query: QueryDSL<T, FunctionMap>;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "read:success";
+        operation: "read";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        query: QueryDSL<T, FunctionMap>;
+    };
+    results: T | T[];
+} | {
+    event: PersistenceEvent<T> & {
+        type: "read:failed";
+        operation: "read";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        query: QueryDSL<T, FunctionMap>;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "update:start";
+        operation: "update";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        data?: Partial<T>;
+        patch?: PatchOperation | Array<PatchOperation>;
+        query: QueryFilter<T, FunctionMap>;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "update:success";
+        operation: "update";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        data?: Partial<T>;
+        patch?: PatchOperation | Array<PatchOperation>;
+        query: QueryFilter<T, FunctionMap>;
+    };
+    results: Array<T>;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "update:failed";
+        operation: "update";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        data?: Partial<T>;
+        patch?: PatchOperation | Array<PatchOperation>;
+        query: QueryFilter<T, FunctionMap>;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "delete:start";
+        operation: "delete";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        query: QueryFilter<T, FunctionMap>;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "delete:success";
+        operation: "delete";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        query: QueryFilter<T, FunctionMap>;
+    };
+    results: number;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "delete:failed";
+        operation: "delete";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        query: QueryFilter<T, FunctionMap>;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "migrate:start";
+        operation: "migrate";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        description: string;
+        dryRun?: boolean;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "migrate:success";
+        operation: "migrate";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        description: string;
+        dryRun?: boolean;
+    };
+    results: {
+        schema: SchemaDefinition;
+        preview: ReadableStream<any>;
+    } | undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "migrate:failed";
+        operation: "migrate";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        description: string;
+        dryRun?: boolean;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "rollback:start";
+        operation: "rollback";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        version?: string;
+        dryRun?: boolean;
+    };
+    results: undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "rollback:success";
+        operation: "rollback";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        version?: string;
+        dryRun?: boolean;
+    };
+    results: {
+        schema: SchemaDefinition;
+        preview: ReadableStream<any>;
+    } | undefined;
+} | {
+    event: PersistenceEvent<T> & {
+        type: "rollback:failed";
+        operation: "rollback";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    params: {
+        version?: string;
+        dryRun?: boolean;
+    };
+    results: undefined;
+};
+/**
+ * Context for global triggers (Persistence-level, non-collection-specific).
  */
-type PersistenceEventType = "create:start" | "create:success" | "create:failed" | "read:start" | "read:success" | "read:failed" | "migrate:start" | "migrate:success" | "migrate:failed" | "rollback:start" | "rollback:success" | "rollback:failed" | "read:failed" | "update:start" | "update:success" | "update:failed" | "delete:start" | "delete:success" | "delete:failed" | "transaction:start" | "transaction:success" | "transaction:failed" | "telemetry" | "collection:create:start" | "collection:create:success" | "collection:create:failed" | "collection:update:start" | "collection:update:success" | "collection:update:failed" | "collection:delete:start" | "collection:delete:success" | "collection:delete:failed";
+type GlobalTriggerContext<T, FunctionMap = Record<string, any>> = {
+    event: PersistenceEvent<T> & {
+        type: "transaction:start" | "transaction:success" | "transaction:failed" | "collection:create:start" | "collection:create:success" | "collection:create:failed" | "collection:delete:start" | "collection:delete:success" | "collection:delete:failed" | "telemetry";
+        operation: "transaction" | "collection:create" | "collection:delete";
+    };
+    persistence: Persistence<FunctionMap>;
+    collection?: undefined;
+    params: any;
+    results: any;
+};
 /**
- * Interface representing events emitted during persistence operations
+ * Union of trigger contexts.
  */
-interface PersistenceEvent<DataType> {
-    /**
-     * The type of event (e.g., 'create:start', 'read:success')
-     */
-    type: PersistenceEventType;
-    /**
-     * Timestamp when the event occurred
-     */
-    timestamp: number;
-    /**
-     * The operation being performed (e.g., 'create', 'read')
-     */
-    operation: string;
-    /**
-     * Name of the collection affected by the operation (if applicable)
-     */
-    collection?: string;
-    /**
-     * Data passed to the operation (if applicable)
-     */
-    input?: any;
-    /**
-     * Data returned by the operation (if applicable)
-     */
-    output?: any;
-    /**
-     * Error object if the operation failed (if applicable)
-     */
-    error?: Error;
-    /**
-     * issues that caused the operation to fail (if applicable)
-     */
-    issues?: Array<StandardSchemaV1.Issue>;
-    /**
-     * Query used in the operation (if applicable)
-     */
-    query?: QueryDSL<DataType, any>;
-    /**
-     * Identifier for the transaction (if part of one)
-     */
-    transactionId?: string;
-    /**
-     * Duration of the operation in milliseconds.
-     * Useful for performance monitoring.
-     */
-    duration?: number;
-    /**
-     * Additional context or metadata specific to the operation.
-     * This field can be used to include extra debugging or contextual data.
-     */
-    context?: Record<string, any>;
-}
+type TriggerContext<T, FunctionMap = Record<string, any>> = CollectionTriggerContext<T, FunctionMap> | GlobalTriggerContext<T, FunctionMap>;
+/**
+ * Defines a schedule for a task.
+ */
+type TaskSchedule = {
+    cron: string;
+} | {
+    at: string;
+} | {
+    interval: number;
+};
+/**
+ * Context provided to task callbacks.
+ */
+type TaskContext<T, FunctionMap = Record<string, any>> = {
+    persistence: Persistence<FunctionMap>;
+    collection: PersistenceCollection<T, FunctionMap>;
+    taskId: string;
+    executionTime: number;
+    metadata?: Record<string, any>;
+    label: string;
+    description: string;
+} | {
+    persistence: Persistence<FunctionMap>;
+    collection?: undefined;
+    taskId: string;
+    executionTime: number;
+    metadata?: Record<string, any>;
+    label: string;
+    description: string;
+};
 
 type SchemaIndex = {
     schema: string;
@@ -1502,9 +2070,10 @@ declare class SchemaRegistry implements SchemaRegistryInterface {
 }
 
 /**
- * @fileoverview Provides a MigrationEngine class that handles schema migrations,
+ * @fileoverview
+ * Provides a MigrationEngine class that handles schema migrations,
  * including validation, checksum generation, and migration application.
- * @author Your Name
+ * @author Saidimu
  */
 
 /**
@@ -1880,4 +2449,4 @@ declare function docgen(schema: SchemaDefinition, options?: {
     faker?: Faker;
 }): string;
 
-export { type ArrayHint, type BooleanHint, type CodeHint, type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type DateHint, type EnumHint, type FieldDefinition, type FieldGroup, type FieldSchema, type FieldType, type FileHint, type FunctionMap, type GroupDefinition, type IndexDefinition, type IndexType, type InputHint, JsonPatchError, type LogicalOperator, type Migration, MigrationEngine, type MigrationEngineInterface, MigrationError, MigrationErrorCode, type MigrationMetadata, type NestedSchemaDefinition, type NumberHint, type ObjectHint, type PartialIndexCondition, type PatchOperation, type Persistence, type PersistenceCollection, type PersistenceEvent, type PersistenceEventType, type PersistenceTransaction, type Predicate, type PredicateMap, type PredicateName, type PredicateParameters, type RegistryLock, type RegistryMetadata, type RemoteRepository, type Schema, type SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaEvent, type SchemaEventType, type SchemaHint, type SchemaIndex, type SchemaMetadata, type SchemaMigrationHelper, SchemaRegistry, type SchemaRegistryInterface, type SchemaVersion, type SecretHint, type SetHint, type TextHint, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createGitSchemaRegistry, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, docgen, extractInputFieldGroups, formResolver, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaDefaults, schemaToTypes, serializeParams, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };
+export { type ArrayHint, type BooleanHint, type CodeHint, type CollectionMetadata, type CollectionTriggerContext, type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type DateHint, type EnumHint, type EventTaskInterface, type FieldDefinition, type FieldGroup, type FieldSchema, type FieldType, type FileHint, type FunctionMap, type GlobalTriggerContext, type GroupDefinition, type IndexDefinition, type IndexType, type InputHint, JsonPatchError, type Metadata, type MetadataFilter, type Migration, MigrationEngine, type MigrationEngineInterface, MigrationError, MigrationErrorCode, type MigrationMetadata, type NestedSchemaDefinition, type NumberHint, type ObjectHint, type ObservabilityInterface, type PartialIndexCondition, type PatchOperation, type Persistence, type PersistenceCollection, type PersistenceEvent, type PersistenceEventType, type PersistenceTransaction, type Predicate, type PredicateMap, type PredicateName, type PredicateParameters, type RegistryLock, type RegistryMetadata, type RemoteRepository, type Schema, type SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaEvent, type SchemaEventType, type SchemaHint, type SchemaIndex, type SchemaMetadata, type SchemaMigrationHelper, SchemaRegistry, type SchemaRegistryInterface, type SchemaVersion, type SecretHint, type SetHint, type SubscriptionInfo, type TaskContext, type TaskInfo, type TaskSchedule, type TextHint, type TransformFunction, type TriggerContext, type TriggerInfo, applyPatch, calculateNextVersion, compareSemanticVersions, createGitSchemaRegistry, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, docgen, extractInputFieldGroups, formResolver, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaDefaults, schemaToTypes, serializeParams, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };