@proseql/core 0.1.0

package/dist/migrations/migration-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-runner.d.ts","sourceRoot":"","sources":["../../src/migrations/migration-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EACX,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAGX,YAAY,EAEZ,SAAS,EACT,MAAM,sBAAsB,CAAC;AAM9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GACzB,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,aAAa,MAAM,EACnB,eAAe,MAAM,EACrB,YAAY,aAAa,CAAC,SAAS,CAAC,EACpC,gBAAgB,MAAM,KACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAwCvD,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,GACrC,gBAAgB,MAAM,EACtB,SAAS,MAAM,EACf,YAAY,aAAa,CAAC,SAAS,CAAC,KAClC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CA6GpC,CAAC;AAMF;;GAEG;AACH,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AACrC,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAC5B,QAAQ,cAAc,EACtB,YAAY,SAAS,KACnB,MAAM,CAAC,MAAM,CACf,YAAY,EACZ,cAAc,GAAG,YAAY,GAAG,kBAAkB,GAAG,sBAAsB,EAC3E,cAAc,GAAG,kBAAkB,CAmHjC,CAAC"}

package/dist/migrations/migration-runner.js

@@ -0,0 +1,271 @@
+/**
+ * Migration Runner
+ *
+ * Core migration logic: validate migration registries, run migrations,
+ * and preview migrations via dry-run.
+ */
+import { Effect } from "effect";
+import { MigrationError } from "../errors/migration-errors.js";
+import { SerializerRegistry } from "../serializers/serializer-service.js";
+import { StorageAdapter } from "../storage/storage-service.js";
+// ============================================================================
+// Migration Execution
+// ============================================================================
+/**
+ * Run migrations to transform data from one version to another.
+ *
+ * Filters migrations to only those applicable for the version transition,
+ * then runs each transform in order, piping the output of one to the input
+ * of the next.
+ *
+ * @param data - The raw entity map to migrate
+ * @param fileVersion - The version of the data (from file's _version, or 0 if absent)
+ * @param targetVersion - The target schema version from collection config
+ * @param migrations - The full migration registry for this collection
+ * @param collectionName - Name of the collection (for error messages)
+ * @returns Effect<Record<string, unknown>, MigrationError> - the migrated data
+ */
+export const runMigrations = (data, fileVersion, targetVersion, migrations, collectionName) => {
+    // If already at target version, no migrations needed
+    if (fileVersion >= targetVersion) {
+        return Effect.succeed(data);
+    }
+    // Filter to migrations that apply: from >= fileVersion and to <= targetVersion
+    // Then sort by `from` to ensure correct execution order
+    const applicableMigrations = migrations
+        .filter((m) => m.from >= fileVersion && m.to <= targetVersion)
+        .sort((a, b) => a.from - b.from);
+    // Run a single migration step, catching any thrown exceptions
+    const runStep = (currentData, migration, stepIndex) => Effect.try({
+        try: () => migration.transform(currentData),
+        catch: (error) => new MigrationError({
+            collection: collectionName,
+            fromVersion: migration.from,
+            toVersion: migration.to,
+            step: stepIndex,
+            reason: "transform-failed",
+            message: `Migration ${migration.from}→${migration.to} failed: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+    });
+    // Chain all migrations using reduce
+    return applicableMigrations.reduce((acc, migration, stepIndex) => acc.pipe(Effect.flatMap((d) => runStep(d, migration, stepIndex))), Effect.succeed(data));
+};
+// ============================================================================
+// Migration Registry Validation
+// ============================================================================
+/**
+ * Validate that a migration registry forms a valid, contiguous chain.
+ *
+ * Validation rules:
+ * - Migrations must form a contiguous chain (no gaps in `from`/`to`)
+ * - Each migration's `to` must equal `from + 1`
+ * - No duplicate `from` values
+ * - The last migration's `to` must equal the collection's `version`
+ * - Version 0 with no migrations is valid
+ * - Version > 0 with empty migrations is invalid
+ *
+ * @param collectionName - Name of the collection (for error messages)
+ * @param version - Target schema version from collection config
+ * @param migrations - Array of migrations to validate
+ * @returns Effect<void, MigrationError> - succeeds if valid, fails with MigrationError if invalid
+ */
+export const validateMigrationRegistry = (collectionName, version, migrations) => {
+    // Version 0 with no migrations is valid (no migrations needed)
+    if (version === 0 && migrations.length === 0) {
+        return Effect.void;
+    }
+    // Version > 0 with empty migrations is invalid (no path from 0 to current)
+    if (version > 0 && migrations.length === 0) {
+        return Effect.fail(new MigrationError({
+            collection: collectionName,
+            fromVersion: 0,
+            toVersion: version,
+            step: -1,
+            reason: "empty-registry",
+            message: `Collection "${collectionName}" has version ${version} but no migrations defined. Cannot migrate from version 0 to ${version}.`,
+        }));
+    }
+    // Check each migration's to === from + 1
+    for (let i = 0; i < migrations.length; i++) {
+        const migration = migrations[i];
+        if (migration.to !== migration.from + 1) {
+            return Effect.fail(new MigrationError({
+                collection: collectionName,
+                fromVersion: migration.from,
+                toVersion: migration.to,
+                step: i,
+                reason: "invalid-increment",
+                message: `Migration at index ${i} has from=${migration.from} and to=${migration.to}, but to must equal from + 1.`,
+            }));
+        }
+    }
+    // Check for duplicate `from` values
+    const fromValues = new Set();
+    for (let i = 0; i < migrations.length; i++) {
+        const migration = migrations[i];
+        if (fromValues.has(migration.from)) {
+            return Effect.fail(new MigrationError({
+                collection: collectionName,
+                fromVersion: migration.from,
+                toVersion: migration.to,
+                step: i,
+                reason: "duplicate-from",
+                message: `Duplicate migration from version ${migration.from}. Each version can only have one migration.`,
+            }));
+        }
+        fromValues.add(migration.from);
+    }
+    // Sort migrations by `from` to check for contiguous chain
+    const sortedMigrations = [...migrations].sort((a, b) => a.from - b.from);
+    // Check that first migration starts from version 0
+    // (data without _version is treated as version 0, so we need a path from 0)
+    const firstMigration = sortedMigrations[0];
+    if (firstMigration.from !== 0) {
+        return Effect.fail(new MigrationError({
+            collection: collectionName,
+            fromVersion: 0,
+            toVersion: firstMigration.from,
+            step: -1,
+            reason: "missing-start",
+            message: `First migration starts at version ${firstMigration.from}, but must start at version 0. No path from version 0 to ${firstMigration.from}.`,
+        }));
+    }
+    // Check for contiguous chain (no gaps)
+    for (let i = 1; i < sortedMigrations.length; i++) {
+        const prev = sortedMigrations[i - 1];
+        const curr = sortedMigrations[i];
+        if (curr.from !== prev.to) {
+            return Effect.fail(new MigrationError({
+                collection: collectionName,
+                fromVersion: prev.to,
+                toVersion: curr.from,
+                step: -1,
+                reason: "gap-in-chain",
+                message: `Gap in migration chain: no migration from version ${prev.to} to ${curr.from}.`,
+            }));
+        }
+    }
+    // Check that last migration's `to` matches the version
+    const lastMigration = sortedMigrations[sortedMigrations.length - 1];
+    if (lastMigration.to !== version) {
+        return Effect.fail(new MigrationError({
+            collection: collectionName,
+            fromVersion: lastMigration.from,
+            toVersion: lastMigration.to,
+            step: -1,
+            reason: "version-mismatch",
+            message: `Last migration goes to version ${lastMigration.to}, but collection version is ${version}.`,
+        }));
+    }
+    return Effect.void;
+};
+/**
+ * Preview which files need migration and what transforms would apply.
+ *
+ * For each versioned collection with a file path:
+ * - Read the file and extract `_version`
+ * - Compare to config `version`
+ * - List which migrations would apply (without running transforms)
+ * - Report status
+ *
+ * No transforms are executed. No files are written.
+ *
+ * @param config - The database configuration
+ * @param _stateRefs - State refs (unused, but kept for API consistency)
+ * @returns Effect<DryRunResult, MigrationError | StorageError | SerializationError | UnsupportedFormatError>
+ */
+export const dryRunMigrations = (config, _stateRefs) => Effect.gen(function* () {
+    const storage = yield* StorageAdapter;
+    const serializer = yield* SerializerRegistry;
+    const collectionResults = [];
+    for (const collectionName of Object.keys(config)) {
+        const collectionConfig = config[collectionName];
+        // Skip unversioned collections
+        if (collectionConfig.version === undefined) {
+            continue;
+        }
+        const targetVersion = collectionConfig.version;
+        const filePath = collectionConfig.file;
+        // Skip collections without a file path
+        if (!filePath) {
+            continue;
+        }
+        // Check if file exists
+        const fileExists = yield* storage.exists(filePath);
+        if (!fileExists) {
+            // File doesn't exist - report as no-file
+            collectionResults.push({
+                name: collectionName,
+                filePath,
+                currentVersion: 0,
+                targetVersion,
+                migrationsToApply: [],
+                status: "no-file",
+            });
+            continue;
+        }
+        // Read and deserialize the file to extract _version
+        const raw = yield* storage.read(filePath);
+        // Extract file extension for deserializer
+        const extMatch = filePath.match(/\.([^.]+)$/);
+        const ext = extMatch ? extMatch[1] : "json";
+        const parsed = yield* serializer.deserialize(raw, ext);
+        // Check if parsed is an object
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            return yield* Effect.fail(new MigrationError({
+                collection: collectionName,
+                fromVersion: 0,
+                toVersion: targetVersion,
+                step: -1,
+                reason: "invalid-file-format",
+                message: `File '${filePath}' does not contain a valid object`,
+            }));
+        }
+        // Extract _version from file (default 0 if absent)
+        const fileVersion = typeof parsed._version === "number"
+            ? parsed._version
+            : 0;
+        // Determine status and migrations to apply
+        let status;
+        let migrationsToApply = [];
+        if (fileVersion > targetVersion) {
+            // File version ahead of config - cannot migrate
+            status = "ahead";
+        }
+        else if (fileVersion === targetVersion) {
+            // Already at target version
+            status = "up-to-date";
+        }
+        else {
+            // File version < target version - needs migration
+            status = "needs-migration";
+            // Filter applicable migrations
+            const migrations = collectionConfig.migrations ?? [];
+            migrationsToApply = migrations
+                .filter((m) => m.from >= fileVersion && m.to <= targetVersion)
+                .sort((a, b) => a.from - b.from)
+                .map((m) => {
+                const result = {
+                    from: m.from,
+                    to: m.to,
+                };
+                if (m.description !== undefined) {
+                    return { ...result, description: m.description };
+                }
+                return result;
+            });
+        }
+        collectionResults.push({
+            name: collectionName,
+            filePath,
+            currentVersion: fileVersion,
+            targetVersion,
+            migrationsToApply,
+            status,
+        });
+    }
+    return { collections: collectionResults };
+});
+//# sourceMappingURL=migration-runner.js.map

package/dist/migrations/migration-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-runner.js","sourceRoot":"","sources":["../../src/migrations/migration-runner.ts"],"names":[],"mappings":"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"}

package/dist/migrations/migration-types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A migration that transforms data from one schema version to the next.
+ *
+ * Migrations are pure synchronous functions that operate on raw deserialized
+ * data (plain objects) before schema decoding. This is necessary because the
+ * old data doesn't conform to the new schema.
+ */
+export interface Migration {
+    /**
+     * Source version (the version being migrated from).
+     */
+    readonly from: number;
+    /**
+     * Target version (must be `from + 1`).
+     */
+    readonly to: number;
+    /**
+     * Transform function that converts the entity map from the source
+     * version to the target version.
+     *
+     * Receives the entire entity map (all entities keyed by ID) and returns
+     * the transformed map. This allows cross-entity transformations.
+     */
+    readonly transform: (data: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Optional human-readable description of what this migration does.
+     * Used in dry-run output.
+     */
+    readonly description?: string;
+}
+/**
+ * Status of a collection in a dry-run result.
+ */
+export type DryRunStatus = "up-to-date" | "needs-migration" | "ahead" | "no-file";
+/**
+ * Information about a single migration that would be applied.
+ */
+export interface DryRunMigration {
+    readonly from: number;
+    readonly to: number;
+    readonly description?: string;
+}
+/**
+ * Status of a single collection in a dry-run result.
+ */
+export interface DryRunCollectionResult {
+    readonly name: string;
+    readonly filePath: string;
+    readonly currentVersion: number;
+    readonly targetVersion: number;
+    readonly migrationsToApply: ReadonlyArray<DryRunMigration>;
+    readonly status: DryRunStatus;
+}
+/**
+ * Result of a dry-run migration check.
+ *
+ * Contains status for each versioned collection, showing which migrations
+ * would be applied without actually executing any transforms or writing files.
+ */
+export interface DryRunResult {
+    readonly collections: ReadonlyArray<DryRunCollectionResult>;
+}
+//# sourceMappingURL=migration-types.d.ts.map

package/dist/migrations/migration-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-types.d.ts","sourceRoot":"","sources":["../../src/migrations/migration-types.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,CACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;GAEG;AACH,MAAM,MAAM,YAAY,GACrB,YAAY,GACZ,iBAAiB,GACjB,OAAO,GACP,SAAS,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC5D"}

package/dist/migrations/migration-types.js

@@ -0,0 +1,5 @@
+// ============================================================================
+// Migration Types
+// ============================================================================
+export {};
+//# sourceMappingURL=migration-types.js.map

package/dist/migrations/migration-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-types.js","sourceRoot":"","sources":["../../src/migrations/migration-types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E"}

package/dist/operations/crud/create-with-relationships.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Effect-based create operations with relationship support.
+ *
+ * Uses Ref<ReadonlyMap> for atomic state mutation, Effect Schema for validation,
+ * and typed errors. Supports $connect, $create, and $connectOrCreate operations
+ * for both ref (single) and inverse (many) relationship types.
+ */
+import { Effect, PubSub, Ref, type Schema } from "effect";
+import { ForeignKeyError, type OperationError, ValidationError } from "../../errors/crud-errors.js";
+import type { ComputedFieldsConfig } from "../../types/computed-types.js";
+import type { CreateWithRelationshipsInput } from "../../types/crud-relationship-types.js";
+import type { ChangeEvent } from "../../types/reactive-types.js";
+import type { RelationshipDef } from "../../types/types.js";
+type HasId = {
+    readonly id: string;
+};
+type RelationshipConfig = {
+    readonly type: "ref" | "inverse";
+    readonly target?: string;
+    readonly __targetCollection?: string;
+    readonly foreignKey?: string;
+};
+type CollectionConfig = {
+    readonly schema: Schema.Schema<HasId, unknown>;
+    readonly relationships: Record<string, RelationshipConfig>;
+};
+type DatabaseConfig = Record<string, CollectionConfig>;
+/**
+ * Create a single entity with relationship support.
+ *
+ * Steps:
+ * 1. Strip computed field keys from input (they are derived, not stored)
+ * 2. Parse relationship operations from input
+ * 3. Generate parent ID early for use in inverse relationships
+ * 4. Process $create: create nested entities in target collections
+ * 5. Process $connectOrCreate: find or create target entities
+ * 6. Process $connect: resolve target entity IDs
+ * 7. Set foreign keys from resolved relationships
+ * 8. Validate and create the parent entity
+ * 9. Update inverse relationship foreign keys on connected entities
+ */
+export declare const createWithRelationships: <T extends HasId, I = T>(collectionName: string, schema: Schema.Schema<T, I>, relationships: Record<string, RelationshipConfig>, ref: Ref.Ref<ReadonlyMap<string, T>>, stateRefs: Record<string, Ref.Ref<ReadonlyMap<string, HasId>>>, dbConfig: DatabaseConfig, computed?: ComputedFieldsConfig<unknown>, changePubSub?: PubSub.PubSub<ChangeEvent>) => (input: CreateWithRelationshipsInput<T, Record<string, RelationshipDef>>) => Effect.Effect<T, ValidationError | ForeignKeyError | OperationError>;
+export {};
+//# sourceMappingURL=create-with-relationships.d.ts.map

package/dist/operations/crud/create-with-relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-with-relationships.d.ts","sourceRoot":"","sources":["../../../src/operations/crud/create-with-relationships.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EACN,eAAe,EACf,KAAK,cAAc,EACnB,eAAe,EACf,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAEX,4BAA4B,EAG5B,MAAM,wCAAwC,CAAC;AAGhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAS5D,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,KAAK,kBAAkB,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC3D,CAAC;AAEF,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AA4WvD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,GAClC,CAAC,SAAS,KAAK,EAAE,CAAC,GAAG,CAAC,EACtB,gBAAgB,MAAM,EACtB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAC3B,eAAe,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACjD,KAAK,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EACpC,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAC9D,UAAU,cAAc,EACxB,WAAW,oBAAoB,CAAC,OAAO,CAAC,EACxC,eAAe,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAGzC,OAAO,4BAA4B,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,KACrE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,eAAe,GAAG,eAAe,GAAG,cAAc,CA4TnE,CAAC"}