@asaidimu/anansi 1.2.0 → 1.2.2

package/index.d.cts

@@ -286,7 +286,7 @@ interface Migration<T> {
  * Defines the interface for a migration engine.
  * The migration engine is responsible for applying, rolling back, and tracking schema migrations.
  */
-interface MigrationEngine<T> {
+interface MigrationEngineInterface<T> {
     /**
      * Applies all pending migrations.
      * @returns A promise that resolves when all migrations are applied.
@@ -413,6 +413,98 @@ declare function createPatch(oldObj: any, newObj: any): PatchOperation[];
  */
 declare function schemaChangeToPatch(change: SchemaChange<any>, schema: SchemaDefinition): PatchOperation[];
 
+/**
+ * Schema event types.
+ */
+type SchemaEventType = SchemaEvent["type"];
+/**
+ * Represents a schema event.
+ */
+type SchemaEvent = {
+    type: "migration:started";
+    description: string;
+    currentVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:committed";
+    currentVersion: string;
+    previousVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:rollingBack";
+    currentVersion: string;
+    targetVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:rolledBack";
+    currentVersion: string;
+    previousVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:ended";
+    currentVersion: string;
+    status: "committed" | "rolledBack";
+};
+/**
+ * Schema interface for managing schema evolution.
+ * @template T The type of data associated with the schema.
+ */
+interface Schema<T = any> {
+    /**
+     * Subscribes to schema events. The listener will be called for each event.
+     * @param event The type of schema event to subscribe to.
+     * @param listener The listener function that receives the schema event.
+     * @returns A function that, when called, unsubscribes the listener.
+     */
+    subscribe(event: SchemaEventType, listener: (event: SchemaEvent) => void): () => void;
+    /**
+     * Returns a read-only copy of the schema definition.
+     * @returns A read-only version of the current schema definition.
+     */
+    definition(): Readonly<SchemaDefinition>;
+    /**
+     * Returns a promise that resolves to a read-only copy of the migration history.
+     * @returns A promise that resolves to a read-only array of migrations.
+     */
+    migrations(): Promise<Readonly<Migration<any>[]>>;
+    /**
+     * Exports the schema state (definition and migrations) as a JSON string.
+     * @returns A JSON string representation of the schema state.
+     */
+    export(): string;
+    /**
+     * Imports the schema state (definition and migrations) from a JSON string.
+     * @param json The JSON string representing the schema state to import.
+     * @throws Error if the imported state is invalid.
+     */
+    import(json: string): void;
+    /**
+     * Creates a migration from a list of changes.
+     * @param description A description of the migration.
+     * @param changes A list of schema changes to apply.
+     * @param dryRun Indicates whether the migration should actually be executed
+     * @throws Error if the changes are not valid.
+     * @returns A promise that resolves when the migration is complete.
+     */
+    migrate(description: string, changes: SchemaChange<T>[], dryRun?: boolean): Promise<void>;
+    /**
+     * Rolls back a migration.
+     * @param version The version to rollback from. If not specified, rolls back the last migration.
+     * @throws Error if the rollback cannot be performed.
+     * @returns A promise that resolves when the rollback is complete.
+     */
+    rollback(version?: string): Promise<void>;
+    /**
+     * Creates a migration helper to assist in creating a migration.
+     * @param description A description of the migration.
+     * @returns A `SchemaMigrationHelper` instance to build the migration.
+     */
+    migrationHelper(description: string): SchemaMigrationHelper;
+}
 /**
  * Helper for building schema migrations.
  * @template T The type of data associated with the schema.
@@ -1600,4 +1692,8 @@ declare function compareSemanticVersions(a: string, b: string): number;
  */
 declare function sortSemanticVars(vars: string[]): string[];
 
-export { type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type FieldDefinition, type FieldType, type FunctionMap, type IndexDefinition, type IndexType, JsonPatchError, type LogicalOperator, type Migration, type MigrationEngine, MigrationError, MigrationErrorCode, type MigrationMetadata, MigrationSchema, 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 SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaIndex, type SchemaMetadata, type SchemaRegistry, type SchemaVersion, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaToTypes, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };
+declare function docgen(schema: SchemaDefinition, options?: {
+    faker?: Faker;
+}): string;
+
+export { type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type FieldDefinition, type FieldType, type FunctionMap, type IndexDefinition, type IndexType, JsonPatchError, type LogicalOperator, type Migration, type MigrationEngineInterface, MigrationError, MigrationErrorCode, type MigrationMetadata, MigrationSchema, 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 Schema, type SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaEvent, type SchemaEventType, type SchemaIndex, type SchemaMetadata, type SchemaMigrationHelper, type SchemaRegistry, type SchemaVersion, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, docgen, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaToTypes, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };

package/index.d.ts

@@ -286,7 +286,7 @@ interface Migration<T> {
  * Defines the interface for a migration engine.
  * The migration engine is responsible for applying, rolling back, and tracking schema migrations.
  */
-interface MigrationEngine<T> {
+interface MigrationEngineInterface<T> {
     /**
      * Applies all pending migrations.
      * @returns A promise that resolves when all migrations are applied.
@@ -413,6 +413,98 @@ declare function createPatch(oldObj: any, newObj: any): PatchOperation[];
  */
 declare function schemaChangeToPatch(change: SchemaChange<any>, schema: SchemaDefinition): PatchOperation[];
 
+/**
+ * Schema event types.
+ */
+type SchemaEventType = SchemaEvent["type"];
+/**
+ * Represents a schema event.
+ */
+type SchemaEvent = {
+    type: "migration:started";
+    description: string;
+    currentVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:committed";
+    currentVersion: string;
+    previousVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:rollingBack";
+    currentVersion: string;
+    targetVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:rolledBack";
+    currentVersion: string;
+    previousVersion: string;
+    changes: SchemaChange<any>[];
+    dryRun?: boolean;
+} | {
+    type: "migration:ended";
+    currentVersion: string;
+    status: "committed" | "rolledBack";
+};
+/**
+ * Schema interface for managing schema evolution.
+ * @template T The type of data associated with the schema.
+ */
+interface Schema<T = any> {
+    /**
+     * Subscribes to schema events. The listener will be called for each event.
+     * @param event The type of schema event to subscribe to.
+     * @param listener The listener function that receives the schema event.
+     * @returns A function that, when called, unsubscribes the listener.
+     */
+    subscribe(event: SchemaEventType, listener: (event: SchemaEvent) => void): () => void;
+    /**
+     * Returns a read-only copy of the schema definition.
+     * @returns A read-only version of the current schema definition.
+     */
+    definition(): Readonly<SchemaDefinition>;
+    /**
+     * Returns a promise that resolves to a read-only copy of the migration history.
+     * @returns A promise that resolves to a read-only array of migrations.
+     */
+    migrations(): Promise<Readonly<Migration<any>[]>>;
+    /**
+     * Exports the schema state (definition and migrations) as a JSON string.
+     * @returns A JSON string representation of the schema state.
+     */
+    export(): string;
+    /**
+     * Imports the schema state (definition and migrations) from a JSON string.
+     * @param json The JSON string representing the schema state to import.
+     * @throws Error if the imported state is invalid.
+     */
+    import(json: string): void;
+    /**
+     * Creates a migration from a list of changes.
+     * @param description A description of the migration.
+     * @param changes A list of schema changes to apply.
+     * @param dryRun Indicates whether the migration should actually be executed
+     * @throws Error if the changes are not valid.
+     * @returns A promise that resolves when the migration is complete.
+     */
+    migrate(description: string, changes: SchemaChange<T>[], dryRun?: boolean): Promise<void>;
+    /**
+     * Rolls back a migration.
+     * @param version The version to rollback from. If not specified, rolls back the last migration.
+     * @throws Error if the rollback cannot be performed.
+     * @returns A promise that resolves when the rollback is complete.
+     */
+    rollback(version?: string): Promise<void>;
+    /**
+     * Creates a migration helper to assist in creating a migration.
+     * @param description A description of the migration.
+     * @returns A `SchemaMigrationHelper` instance to build the migration.
+     */
+    migrationHelper(description: string): SchemaMigrationHelper;
+}
 /**
  * Helper for building schema migrations.
  * @template T The type of data associated with the schema.
@@ -1600,4 +1692,8 @@ declare function compareSemanticVersions(a: string, b: string): number;
  */
 declare function sortSemanticVars(vars: string[]): string[];
 
-export { type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type FieldDefinition, type FieldType, type FunctionMap, type IndexDefinition, type IndexType, JsonPatchError, type LogicalOperator, type Migration, type MigrationEngine, MigrationError, MigrationErrorCode, type MigrationMetadata, MigrationSchema, 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 SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaIndex, type SchemaMetadata, type SchemaRegistry, type SchemaVersion, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaToTypes, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };
+declare function docgen(schema: SchemaDefinition, options?: {
+    faker?: Faker;
+}): string;
+
+export { type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type FieldDefinition, type FieldType, type FunctionMap, type IndexDefinition, type IndexType, JsonPatchError, type LogicalOperator, type Migration, type MigrationEngineInterface, MigrationError, MigrationErrorCode, type MigrationMetadata, MigrationSchema, 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 Schema, type SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaEvent, type SchemaEventType, type SchemaIndex, type SchemaMetadata, type SchemaMigrationHelper, type SchemaRegistry, type SchemaVersion, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, docgen, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaToTypes, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };