pocketbase-zod-schema 0.1.2

package/dist/migration/diff.d.cts

@@ -0,0 +1,291 @@
+import { S as SchemaDefinition, a as SchemaSnapshot, f as SchemaDiff, F as FieldDefinition, b as FieldChange, C as CollectionSchema, d as PermissionChange } from '../types-BbTgmg6H.cjs';
+import '../permissions-ZHafVSIx.cjs';
+
+/**
+ * Diff Engine component
+ * Compares current schema with previous snapshot and identifies changes
+ *
+ * This module provides a standalone, configurable diff engine that can be used
+ * by consumer projects to compare schema definitions and detect changes.
+ */
+
+/**
+ * Configuration options for the diff engine
+ */
+interface DiffEngineConfig {
+    /**
+     * Whether to warn on collection deletions
+     * Defaults to true
+     */
+    warnOnDelete?: boolean;
+    /**
+     * Whether to require --force flag for destructive changes
+     * Defaults to true
+     */
+    requireForceForDestructive?: boolean;
+    /**
+     * Severity threshold for requiring force flag
+     * 'high' = only collection/field deletions and type changes
+     * 'medium' = includes making fields required
+     * 'low' = includes any constraint changes
+     * Defaults to 'high'
+     */
+    severityThreshold?: "high" | "medium" | "low";
+    /**
+     * Custom system collections to exclude from diff
+     * These collections will not be created or deleted
+     */
+    systemCollections?: string[];
+    /**
+     * Custom system fields to exclude from user collection diffs
+     * These fields will not be included in fieldsToAdd for the users collection
+     */
+    usersSystemFields?: string[];
+}
+/**
+ * Destructive change information
+ */
+interface DestructiveChange {
+    type: "collection_delete" | "field_delete" | "type_change" | "required_change" | "constraint_change";
+    severity: "high" | "medium" | "low";
+    collection: string;
+    field?: string;
+    description: string;
+    oldValue?: any;
+    newValue?: any;
+}
+/**
+ * Change summary for status reporting
+ */
+interface ChangeSummary {
+    totalChanges: number;
+    collectionsToCreate: number;
+    collectionsToDelete: number;
+    collectionsToModify: number;
+    fieldsToAdd: number;
+    fieldsToRemove: number;
+    fieldsToModify: number;
+    indexChanges: number;
+    ruleChanges: number;
+    permissionChanges: number;
+    destructiveChanges: DestructiveChange[];
+    nonDestructiveChanges: string[];
+}
+/**
+ * Checks if a collection is a PocketBase system collection
+ * System collections are internal to PocketBase and should not be created or deleted
+ *
+ * @param collectionName - Name of the collection to check
+ * @param config - Optional configuration with custom system collections
+ * @returns True if the collection is a system collection
+ */
+declare function isSystemCollection(collectionName: string, config?: DiffEngineConfig): boolean;
+/**
+ * Returns the list of system field names for the users collection
+ * These fields are automatically provided by PocketBase for auth collections
+ * and should not be included when generating migrations for users collection extensions
+ *
+ * @param config - Optional configuration with custom system fields
+ * @returns Set of system field names
+ */
+declare function getUsersSystemFields(config?: DiffEngineConfig): Set<string>;
+/**
+ * Filters system collections from a schema definition
+ * Returns a new SchemaDefinition with only custom (non-system) collections
+ *
+ * @param schema - Schema definition to filter
+ * @param config - Optional configuration
+ * @returns Filtered SchemaDefinition without system collections
+ */
+declare function filterSystemCollections(schema: SchemaDefinition, config?: DiffEngineConfig): SchemaDefinition;
+/**
+ * Identifies new collections in schema that don't exist in snapshot
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @returns Array of new collections
+ */
+declare function findNewCollections(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): CollectionSchema[];
+/**
+ * Identifies collections removed from schema (exist in snapshot but not in current schema)
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @returns Array of removed collections
+ */
+declare function findRemovedCollections(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): CollectionSchema[];
+/**
+ * Matches collections by name between current schema and snapshot
+ * Returns pairs of [current, previous] for collections that exist in both
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @returns Array of matched collection pairs
+ */
+declare function matchCollectionsByName(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): Array<[CollectionSchema, CollectionSchema]>;
+/**
+ * Identifies new fields in current collection that don't exist in previous
+ *
+ * @param currentFields - Current collection fields
+ * @param previousFields - Previous collection fields
+ * @returns Array of new fields
+ */
+declare function findNewFields(currentFields: FieldDefinition[], previousFields: FieldDefinition[]): FieldDefinition[];
+/**
+ * Identifies fields removed from current collection (exist in previous but not in current)
+ *
+ * @param currentFields - Current collection fields
+ * @param previousFields - Previous collection fields
+ * @returns Array of removed fields
+ */
+declare function findRemovedFields(currentFields: FieldDefinition[], previousFields: FieldDefinition[]): FieldDefinition[];
+/**
+ * Matches fields by name between current and previous collections
+ * Returns pairs of [current, previous] for fields that exist in both
+ *
+ * @param currentFields - Current collection fields
+ * @param previousFields - Previous collection fields
+ * @returns Array of matched field pairs
+ */
+declare function matchFieldsByName(currentFields: FieldDefinition[], previousFields: FieldDefinition[]): Array<[FieldDefinition, FieldDefinition]>;
+/**
+ * Compares field types between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns FieldChange if types differ, null otherwise
+ */
+declare function compareFieldTypes(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange | null;
+/**
+ * Compares field constraints (required, unique) between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of FieldChange for constraint differences
+ */
+declare function compareFieldConstraints(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Compares field options (min, max, pattern, etc.) between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of FieldChange for option differences
+ */
+declare function compareFieldOptions(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Compares relation configurations between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of FieldChange for relation differences
+ */
+declare function compareRelationConfigurations(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Detects all changes between two field definitions
+ * Combines type, constraint, option, and relation changes
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of all detected changes
+ */
+declare function detectFieldChanges(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Compares permissions between current and previous collections
+ * Detects changes in permission rules defined in schema
+ *
+ * @param currentPermissions - Current collection permissions
+ * @param previousPermissions - Previous collection permissions
+ * @returns Array of permission changes
+ */
+declare function comparePermissions(currentPermissions: CollectionSchema["permissions"], previousPermissions: CollectionSchema["permissions"]): PermissionChange[];
+/**
+ * Aggregates all detected changes into a SchemaDiff
+ * Main entry point for diff comparison
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @param config - Optional configuration
+ * @returns Complete SchemaDiff with all changes
+ */
+declare function aggregateChanges(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null, config?: DiffEngineConfig): SchemaDiff;
+/**
+ * Detects destructive changes in a schema diff
+ * Returns detailed information about each destructive change
+ *
+ * @param diff - Schema diff to analyze
+ * @param config - Optional configuration for severity thresholds
+ * @returns Array of destructive changes with severity information
+ */
+declare function detectDestructiveChanges(diff: SchemaDiff, config?: DiffEngineConfig): DestructiveChange[];
+/**
+ * Categorizes changes by severity
+ * Returns object with destructive and non-destructive changes
+ *
+ * @param diff - Schema diff to categorize
+ * @param config - Optional configuration
+ * @returns Object with categorized changes
+ */
+declare function categorizeChangesBySeverity(diff: SchemaDiff, _config?: DiffEngineConfig): {
+    destructive: string[];
+    nonDestructive: string[];
+};
+/**
+ * Generates a summary of all changes in a diff
+ * Useful for status reporting and user feedback
+ *
+ * @param diff - Schema diff to summarize
+ * @param config - Optional configuration
+ * @returns Change summary with counts and details
+ */
+declare function generateChangeSummary(diff: SchemaDiff, config?: DiffEngineConfig): ChangeSummary;
+/**
+ * Checks if a diff requires the --force flag based on configuration
+ *
+ * @param diff - Schema diff to check
+ * @param config - Configuration with severity threshold
+ * @returns True if force flag is required
+ */
+declare function requiresForceFlag(diff: SchemaDiff, config?: DiffEngineConfig): boolean;
+/**
+ * Main comparison function
+ * Compares current schema with previous snapshot and returns complete diff
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot (null for first run)
+ * @param config - Optional configuration
+ * @returns Complete SchemaDiff with all detected changes
+ */
+declare function compare(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null, config?: DiffEngineConfig): SchemaDiff;
+/**
+ * DiffEngine class for object-oriented usage
+ * Provides a stateful interface for schema comparison
+ */
+declare class DiffEngine {
+    private config;
+    constructor(config?: DiffEngineConfig);
+    /**
+     * Compares current schema with previous snapshot
+     */
+    compare(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): SchemaDiff;
+    /**
+     * Detects destructive changes in a diff
+     */
+    detectDestructiveChanges(diff: SchemaDiff): DestructiveChange[];
+    /**
+     * Categorizes changes by severity
+     */
+    categorizeChangesBySeverity(diff: SchemaDiff): {
+        destructive: string[];
+        nonDestructive: string[];
+    };
+    /**
+     * Generates a summary of changes
+     */
+    generateChangeSummary(diff: SchemaDiff): ChangeSummary;
+    /**
+     * Checks if force flag is required
+     */
+    requiresForceFlag(diff: SchemaDiff): boolean;
+}
+
+export { type ChangeSummary, type DestructiveChange, DiffEngine, type DiffEngineConfig, aggregateChanges, categorizeChangesBySeverity, compare, compareFieldConstraints, compareFieldOptions, compareFieldTypes, comparePermissions, compareRelationConfigurations, detectDestructiveChanges, detectFieldChanges, filterSystemCollections, findNewCollections, findNewFields, findRemovedCollections, findRemovedFields, generateChangeSummary, getUsersSystemFields, isSystemCollection, matchCollectionsByName, matchFieldsByName, requiresForceFlag };

package/dist/migration/diff.d.ts

@@ -0,0 +1,291 @@
+import { S as SchemaDefinition, a as SchemaSnapshot, f as SchemaDiff, F as FieldDefinition, b as FieldChange, C as CollectionSchema, d as PermissionChange } from '../types-z1Dkjg8m.js';
+import '../permissions-ZHafVSIx.js';
+
+/**
+ * Diff Engine component
+ * Compares current schema with previous snapshot and identifies changes
+ *
+ * This module provides a standalone, configurable diff engine that can be used
+ * by consumer projects to compare schema definitions and detect changes.
+ */
+
+/**
+ * Configuration options for the diff engine
+ */
+interface DiffEngineConfig {
+    /**
+     * Whether to warn on collection deletions
+     * Defaults to true
+     */
+    warnOnDelete?: boolean;
+    /**
+     * Whether to require --force flag for destructive changes
+     * Defaults to true
+     */
+    requireForceForDestructive?: boolean;
+    /**
+     * Severity threshold for requiring force flag
+     * 'high' = only collection/field deletions and type changes
+     * 'medium' = includes making fields required
+     * 'low' = includes any constraint changes
+     * Defaults to 'high'
+     */
+    severityThreshold?: "high" | "medium" | "low";
+    /**
+     * Custom system collections to exclude from diff
+     * These collections will not be created or deleted
+     */
+    systemCollections?: string[];
+    /**
+     * Custom system fields to exclude from user collection diffs
+     * These fields will not be included in fieldsToAdd for the users collection
+     */
+    usersSystemFields?: string[];
+}
+/**
+ * Destructive change information
+ */
+interface DestructiveChange {
+    type: "collection_delete" | "field_delete" | "type_change" | "required_change" | "constraint_change";
+    severity: "high" | "medium" | "low";
+    collection: string;
+    field?: string;
+    description: string;
+    oldValue?: any;
+    newValue?: any;
+}
+/**
+ * Change summary for status reporting
+ */
+interface ChangeSummary {
+    totalChanges: number;
+    collectionsToCreate: number;
+    collectionsToDelete: number;
+    collectionsToModify: number;
+    fieldsToAdd: number;
+    fieldsToRemove: number;
+    fieldsToModify: number;
+    indexChanges: number;
+    ruleChanges: number;
+    permissionChanges: number;
+    destructiveChanges: DestructiveChange[];
+    nonDestructiveChanges: string[];
+}
+/**
+ * Checks if a collection is a PocketBase system collection
+ * System collections are internal to PocketBase and should not be created or deleted
+ *
+ * @param collectionName - Name of the collection to check
+ * @param config - Optional configuration with custom system collections
+ * @returns True if the collection is a system collection
+ */
+declare function isSystemCollection(collectionName: string, config?: DiffEngineConfig): boolean;
+/**
+ * Returns the list of system field names for the users collection
+ * These fields are automatically provided by PocketBase for auth collections
+ * and should not be included when generating migrations for users collection extensions
+ *
+ * @param config - Optional configuration with custom system fields
+ * @returns Set of system field names
+ */
+declare function getUsersSystemFields(config?: DiffEngineConfig): Set<string>;
+/**
+ * Filters system collections from a schema definition
+ * Returns a new SchemaDefinition with only custom (non-system) collections
+ *
+ * @param schema - Schema definition to filter
+ * @param config - Optional configuration
+ * @returns Filtered SchemaDefinition without system collections
+ */
+declare function filterSystemCollections(schema: SchemaDefinition, config?: DiffEngineConfig): SchemaDefinition;
+/**
+ * Identifies new collections in schema that don't exist in snapshot
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @returns Array of new collections
+ */
+declare function findNewCollections(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): CollectionSchema[];
+/**
+ * Identifies collections removed from schema (exist in snapshot but not in current schema)
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @returns Array of removed collections
+ */
+declare function findRemovedCollections(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): CollectionSchema[];
+/**
+ * Matches collections by name between current schema and snapshot
+ * Returns pairs of [current, previous] for collections that exist in both
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @returns Array of matched collection pairs
+ */
+declare function matchCollectionsByName(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): Array<[CollectionSchema, CollectionSchema]>;
+/**
+ * Identifies new fields in current collection that don't exist in previous
+ *
+ * @param currentFields - Current collection fields
+ * @param previousFields - Previous collection fields
+ * @returns Array of new fields
+ */
+declare function findNewFields(currentFields: FieldDefinition[], previousFields: FieldDefinition[]): FieldDefinition[];
+/**
+ * Identifies fields removed from current collection (exist in previous but not in current)
+ *
+ * @param currentFields - Current collection fields
+ * @param previousFields - Previous collection fields
+ * @returns Array of removed fields
+ */
+declare function findRemovedFields(currentFields: FieldDefinition[], previousFields: FieldDefinition[]): FieldDefinition[];
+/**
+ * Matches fields by name between current and previous collections
+ * Returns pairs of [current, previous] for fields that exist in both
+ *
+ * @param currentFields - Current collection fields
+ * @param previousFields - Previous collection fields
+ * @returns Array of matched field pairs
+ */
+declare function matchFieldsByName(currentFields: FieldDefinition[], previousFields: FieldDefinition[]): Array<[FieldDefinition, FieldDefinition]>;
+/**
+ * Compares field types between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns FieldChange if types differ, null otherwise
+ */
+declare function compareFieldTypes(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange | null;
+/**
+ * Compares field constraints (required, unique) between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of FieldChange for constraint differences
+ */
+declare function compareFieldConstraints(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Compares field options (min, max, pattern, etc.) between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of FieldChange for option differences
+ */
+declare function compareFieldOptions(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Compares relation configurations between current and previous
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of FieldChange for relation differences
+ */
+declare function compareRelationConfigurations(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Detects all changes between two field definitions
+ * Combines type, constraint, option, and relation changes
+ *
+ * @param currentField - Current field definition
+ * @param previousField - Previous field definition
+ * @returns Array of all detected changes
+ */
+declare function detectFieldChanges(currentField: FieldDefinition, previousField: FieldDefinition): FieldChange[];
+/**
+ * Compares permissions between current and previous collections
+ * Detects changes in permission rules defined in schema
+ *
+ * @param currentPermissions - Current collection permissions
+ * @param previousPermissions - Previous collection permissions
+ * @returns Array of permission changes
+ */
+declare function comparePermissions(currentPermissions: CollectionSchema["permissions"], previousPermissions: CollectionSchema["permissions"]): PermissionChange[];
+/**
+ * Aggregates all detected changes into a SchemaDiff
+ * Main entry point for diff comparison
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot
+ * @param config - Optional configuration
+ * @returns Complete SchemaDiff with all changes
+ */
+declare function aggregateChanges(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null, config?: DiffEngineConfig): SchemaDiff;
+/**
+ * Detects destructive changes in a schema diff
+ * Returns detailed information about each destructive change
+ *
+ * @param diff - Schema diff to analyze
+ * @param config - Optional configuration for severity thresholds
+ * @returns Array of destructive changes with severity information
+ */
+declare function detectDestructiveChanges(diff: SchemaDiff, config?: DiffEngineConfig): DestructiveChange[];
+/**
+ * Categorizes changes by severity
+ * Returns object with destructive and non-destructive changes
+ *
+ * @param diff - Schema diff to categorize
+ * @param config - Optional configuration
+ * @returns Object with categorized changes
+ */
+declare function categorizeChangesBySeverity(diff: SchemaDiff, _config?: DiffEngineConfig): {
+    destructive: string[];
+    nonDestructive: string[];
+};
+/**
+ * Generates a summary of all changes in a diff
+ * Useful for status reporting and user feedback
+ *
+ * @param diff - Schema diff to summarize
+ * @param config - Optional configuration
+ * @returns Change summary with counts and details
+ */
+declare function generateChangeSummary(diff: SchemaDiff, config?: DiffEngineConfig): ChangeSummary;
+/**
+ * Checks if a diff requires the --force flag based on configuration
+ *
+ * @param diff - Schema diff to check
+ * @param config - Configuration with severity threshold
+ * @returns True if force flag is required
+ */
+declare function requiresForceFlag(diff: SchemaDiff, config?: DiffEngineConfig): boolean;
+/**
+ * Main comparison function
+ * Compares current schema with previous snapshot and returns complete diff
+ *
+ * @param currentSchema - Current schema definition
+ * @param previousSnapshot - Previous schema snapshot (null for first run)
+ * @param config - Optional configuration
+ * @returns Complete SchemaDiff with all detected changes
+ */
+declare function compare(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null, config?: DiffEngineConfig): SchemaDiff;
+/**
+ * DiffEngine class for object-oriented usage
+ * Provides a stateful interface for schema comparison
+ */
+declare class DiffEngine {
+    private config;
+    constructor(config?: DiffEngineConfig);
+    /**
+     * Compares current schema with previous snapshot
+     */
+    compare(currentSchema: SchemaDefinition, previousSnapshot: SchemaSnapshot | null): SchemaDiff;
+    /**
+     * Detects destructive changes in a diff
+     */
+    detectDestructiveChanges(diff: SchemaDiff): DestructiveChange[];
+    /**
+     * Categorizes changes by severity
+     */
+    categorizeChangesBySeverity(diff: SchemaDiff): {
+        destructive: string[];
+        nonDestructive: string[];
+    };
+    /**
+     * Generates a summary of changes
+     */
+    generateChangeSummary(diff: SchemaDiff): ChangeSummary;
+    /**
+     * Checks if force flag is required
+     */
+    requiresForceFlag(diff: SchemaDiff): boolean;
+}
+
+export { type ChangeSummary, type DestructiveChange, DiffEngine, type DiffEngineConfig, aggregateChanges, categorizeChangesBySeverity, compare, compareFieldConstraints, compareFieldOptions, compareFieldTypes, comparePermissions, compareRelationConfigurations, detectDestructiveChanges, detectFieldChanges, filterSystemCollections, findNewCollections, findNewFields, findRemovedCollections, findRemovedFields, generateChangeSummary, getUsersSystemFields, isSystemCollection, matchCollectionsByName, matchFieldsByName, requiresForceFlag };