@relations-dil/relations 0.1.0

package/dist/migrations.js

@@ -0,0 +1,293 @@
+/**
+ * Migrations: diffing model definitions over time, and handing the diffs to a source.
+ *
+ * Definitions are backend-neutral JSON. A source converts them into whatever it needs -
+ * DDL for a database, nothing at all for an API - so the same migration history drives
+ * every backend a set of models is used with.
+ */
+import { mkdir, readdir, readFile, rename as renameFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MigrationsError } from './errors.js';
+import { source as registered } from './registry.js';
+import { equal } from './util.js';
+import { MigrationsRef } from './model.js';
+const noRenames = () => ({});
+/** Diffs model definitions and drives a source through the resulting changes. */
+export class Migrations {
+    /** Directory the definition and migration files live in. */
+    directory;
+    /** How renames are decided. Defaults to treating nothing as a rename. */
+    renamer;
+    constructor(directory = 'ddl', options = {}) {
+        this.directory = directory;
+        this.renamer = options.renamer ?? noRenames;
+    }
+    /** The definition as of the last generate, or an empty one. */
+    async current() {
+        try {
+            return JSON.parse(await readFile(join(this.directory, 'definition.json'), 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return {};
+            }
+            throw error;
+        }
+    }
+    /** Definitions for a set of model classes, keyed by model name. */
+    static define(models) {
+        const definitions = {};
+        for (const model of models) {
+            const definition = model.thy().define();
+            definitions[definition.name] = definition;
+        }
+        return definitions;
+    }
+    /** Work out which removals are renames, and take those out of adds and removes. */
+    static rename(renamer, name, adds, removes) {
+        if (!adds.length || !removes.length) {
+            return {};
+        }
+        const renames = renamer(name, [...adds], [...removes]);
+        for (const [remove, add] of Object.entries(renames)) {
+            const removeAt = removes.indexOf(remove);
+            const addAt = adds.indexOf(add);
+            if (removeAt === -1 || addAt === -1) {
+                throw new MigrationsError(`${name} rename ${remove} to ${add} is not in the changes`);
+            }
+            removes.splice(removeAt, 1);
+            adds.splice(addAt, 1);
+        }
+        return renames;
+    }
+    /** A field definition by name. */
+    static lookup(name, fields) {
+        for (const field of fields) {
+            if (name === field.name) {
+                return field;
+            }
+        }
+        return null;
+    }
+    /** What changed between two field definitions. */
+    static field(current, define) {
+        const migration = {};
+        for (const attr of new Set([...Object.keys(current), ...Object.keys(define)])) {
+            if (!equal(current[attr], define[attr])) {
+                migration[attr] = define[attr] ?? null;
+            }
+        }
+        return migration;
+    }
+    /** What changed between two sets of field definitions. */
+    static fields(renamer, model, current, define) {
+        const migration = {};
+        const currentNames = current.map((field) => field.name);
+        const defineNames = define.map((field) => field.name);
+        const add = defineNames.filter((name) => !currentNames.includes(name));
+        const remove = currentNames.filter((name) => !defineNames.includes(name));
+        const renames = Migrations.rename(renamer, `${model} fields`, add, remove);
+        if (add.length) {
+            migration.add = define.filter((field) => add.includes(field.name));
+        }
+        if (remove.length) {
+            migration.remove = remove;
+        }
+        const change = {};
+        for (const currentField of current) {
+            const defineField = Migrations.lookup(renames[currentField.name] ?? currentField.name, define);
+            if (defineField !== null && !equal(currentField, defineField)) {
+                change[currentField.name] = Migrations.field(currentField, defineField);
+            }
+        }
+        if (Object.keys(change).length) {
+            migration.change = change;
+        }
+        return migration;
+    }
+    /** What changed between two sets of indexes. */
+    static indexes(renamer, model, kind, current, define) {
+        const migration = {};
+        const add = Object.keys(define)
+            .sort()
+            .filter((name) => !(name in current));
+        const remove = Object.keys(current)
+            .sort()
+            .filter((name) => !(name in define));
+        const renames = Migrations.rename(renamer, `${model} ${kind}`, add, remove);
+        if (add.length) {
+            migration.add = Object.fromEntries(add.map((name) => [name, define[name]]));
+        }
+        if (remove.length) {
+            migration.remove = remove;
+        }
+        if (Object.keys(renames).length) {
+            for (const [currentName, defineName] of Object.entries(renames)) {
+                if (!equal(current[currentName], define[defineName])) {
+                    throw new MigrationsError(`${model} ${kind} ${currentName} and ${defineName} must have same fields to rename`);
+                }
+            }
+            migration.rename = renames;
+        }
+        return migration;
+    }
+    /** What changed between two model definitions. */
+    static model(current, define, renamer = noRenames) {
+        const model = current.name !== define.name ? `${current.name}/${define.name}` : current.name;
+        const migration = {};
+        const attrs = new Set(['name', 'title', 'id', ...Object.keys(current), ...Object.keys(define)]);
+        for (const attr of attrs) {
+            if (['fields', 'index', 'unique'].includes(attr)) {
+                continue;
+            }
+            if (!equal(current[attr], define[attr])) {
+                migration[attr] = define[attr] ?? null;
+            }
+        }
+        if (!equal(current.fields, define.fields)) {
+            migration.fields = Migrations.fields(renamer, model, current.fields, define.fields);
+        }
+        for (const attr of ['unique', 'index']) {
+            const kind = attr === 'unique' ? 'unique indexes' : 'indexes';
+            if (!equal(current[attr], define[attr])) {
+                migration[attr] = Migrations.indexes(renamer, model, kind, current[attr] ?? {}, define[attr] ?? {});
+            }
+        }
+        return migration;
+    }
+    /** What changed across a whole set of models. */
+    static models(current, define, renamer = noRenames) {
+        const migration = {};
+        const add = Object.keys(define)
+            .sort()
+            .filter((name) => !(name in current));
+        const remove = Object.keys(current)
+            .sort()
+            .filter((name) => !(name in define));
+        const renames = Migrations.rename(renamer, 'models', add, remove);
+        if (add.length) {
+            migration.add = Object.fromEntries(add.map((name) => [name, define[name]]));
+        }
+        if (remove.length) {
+            migration.remove = Object.fromEntries(remove.map((name) => [name, current[name]]));
+        }
+        const change = {};
+        for (const name of Object.keys(current)) {
+            const defineModel = define[renames[name] ?? name];
+            if (defineModel !== undefined && !equal(current[name], defineModel)) {
+                change[name] = {
+                    definition: current[name],
+                    migration: Migrations.model(current[name], defineModel, renamer)
+                };
+            }
+        }
+        if (Object.keys(change).length) {
+            migration.change = change;
+        }
+        return migration;
+    }
+    /**
+     * Snapshot the current models, writing a migration alongside the previous snapshot.
+     * Resolves to whether anything was written.
+     */
+    async generate(models, stamp) {
+        await mkdir(this.directory, { recursive: true });
+        const current = await this.current();
+        const define = Migrations.define(models);
+        if (Object.keys(current).length) {
+            if (equal(current, define)) {
+                return false;
+            }
+            const migration = Migrations.models(current, define, this.renamer);
+            const at = stamp ?? stamped();
+            await renameFile(join(this.directory, 'definition.json'), join(this.directory, `definition-${at}.json`));
+            await writeFile(join(this.directory, `migration-${at}.json`), pretty(migration));
+        }
+        await writeFile(join(this.directory, 'definition.json'), pretty(define));
+        return true;
+    }
+    /** Where a source's converted files live. */
+    sourcePath(name) {
+        const source = registered(name);
+        if (source === undefined) {
+            throw new MigrationsError(`no source registered as '${name}'`);
+        }
+        return join(this.directory, source.name, String(source.KIND));
+    }
+    /** Convert every definition and migration into a source's own form. */
+    async convert(name) {
+        const source = registered(name);
+        if (source === undefined) {
+            throw new MigrationsError(`no source registered as '${name}'`);
+        }
+        const path = this.sourcePath(name);
+        await mkdir(path, { recursive: true });
+        for (const file of (await readdir(this.directory)).sort()) {
+            if (!file.endsWith('.json')) {
+                continue;
+            }
+            if (file.startsWith('definition')) {
+                await source.definition(join(this.directory, file), path);
+            }
+            else if (file.startsWith('migration')) {
+                await source.migration(join(this.directory, file), path);
+            }
+        }
+    }
+    /** The migration pairs available for a source. */
+    async list(name) {
+        const source = registered(name);
+        if (source === undefined) {
+            throw new MigrationsError(`no source registered as '${name}'`);
+        }
+        return source.list(this.sourcePath(name));
+    }
+    /** Load one converted file into a source. */
+    async load(name, fileName) {
+        const source = registered(name);
+        if (source === undefined) {
+            throw new MigrationsError(`no source registered as '${name}'`);
+        }
+        return source.load(join(this.sourcePath(name), fileName));
+    }
+    /** Bring a source up to date. Resolves to whether anything was applied. */
+    async apply(name) {
+        const source = registered(name);
+        if (source === undefined) {
+            throw new MigrationsError(`no source registered as '${name}'`);
+        }
+        return source.migrate(this.sourcePath(name));
+    }
+}
+/** Sorted-key JSON, so definitions diff cleanly in version control. */
+export function pretty(value) {
+    return `${JSON.stringify(value, (_key, item) => ordered(item), 4)}\n`;
+}
+function ordered(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return value;
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        return value;
+    }
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = value[key];
+    }
+    return sorted;
+}
+function stamped(at = new Date()) {
+    const pad = (value, width = 2) => String(value).padStart(width, '0');
+    return [
+        at.getFullYear(),
+        pad(at.getMonth() + 1),
+        pad(at.getDate()),
+        pad(at.getHours()),
+        pad(at.getMinutes()),
+        pad(at.getSeconds()),
+        pad(at.getMilliseconds() * 1000, 6)
+    ].join('-');
+}
+// Let a model identity diff itself without importing this module.
+MigrationsRef.model = (current, define) => Migrations.model(current, define);
+//# sourceMappingURL=migrations.js.map

package/dist/mock.d.ts

@@ -0,0 +1,88 @@
+/**
+ * An in-memory source.
+ *
+ * Everything relations can do, done against plain objects in this process. Use it in
+ * tests, in examples, and to feel out a model's shape before you pick a backend.
+ *
+ * ```ts
+ * import { MockSource } from '@relations-dil/relations/mock'
+ *
+ * new MockSource('example')
+ * ```
+ */
+import { Source, type Query } from './source.js';
+import { Titles } from './titles.js';
+import { type Model, type ModelIdentity } from './model.js';
+/** A stand-in for a real source's query object. */
+export declare class MockQuery implements Query {
+    /** What the query would do. */
+    action: string;
+    /** The model it was built for. */
+    model: Model | null;
+    constructor(action: string);
+    /** Attach the model, the way a real query builder would. */
+    bind(model: Model): this;
+}
+type Stored = globalThis.Record<string, any>;
+/** A complete source that keeps everything in memory. */
+export declare class MockSource extends Source {
+    static KIND: string;
+    /** Query classes, so tests can assert on what would run. */
+    SELECT: typeof MockQuery;
+    INSERT: typeof MockQuery;
+    UPDATE: typeof MockQuery;
+    DELETE: typeof MockQuery;
+    /** Last id handed out, keyed by model name. */
+    ids: globalThis.Record<string, number>;
+    /** Records keyed by id, keyed by model name. */
+    data: globalThis.Record<string, Map<number, Stored>>;
+    /** Unique index values keyed by id, keyed by index, keyed by model name. */
+    unique: globalThis.Record<string, globalThis.Record<string, Map<number, string>>>;
+    /** Migrations applied so far, or null when nothing has been loaded. */
+    migrations: string[] | null;
+    /** Snapshot taken while a write is in flight, so a failure can roll back. */
+    transaction: [typeof this.ids, typeof this.data, typeof this.unique] | null;
+    constructor(name: string, options?: globalThis.Record<string, any>);
+    /** Make room for a model, and give it an auto id if it has an id field. */
+    init(model: ModelIdentity): void;
+    fieldDefine(field: Stored, definitions: Stored[]): void;
+    define(model: Stored): Stored[];
+    fieldAdd(migration: Stored, migrations: Stored[]): void;
+    fieldRemove(definition: Stored, migrations: Stored[]): void;
+    fieldChange(definition: Stored, migration: Stored, migrations: Stored[]): void;
+    modelAdd(definition: Stored): Stored[];
+    modelRemove(definition: Stored): Stored[];
+    modelChange(definition: Stored, migration: Stored): Stored[];
+    /** Copy extracted paths out of container fields into their own stored keys. */
+    static extract(model: Model, values: Stored): Stored;
+    /** Check every unique index, recording the new value or throwing. */
+    uniques(model: Model, values: Stored, id: number): void;
+    /** Run a write with a snapshot in place, restoring it if the write fails. */
+    private rolling;
+    createQuery(model: Model): Query;
+    create(model: Model): Promise<Model>;
+    /** The records matching a fuzzy `like`, including matches through parent titles. */
+    modelLike(model: Model): Promise<Stored[]>;
+    /** Apply the model's sort, or its default order. */
+    static modelSort(model: Model): void;
+    /** Apply the model's limit, flagging overflow when it was reached. */
+    static modelLimit(model: Model): void;
+    countQuery(model: Model): Query;
+    count(model: Model): Promise<number>;
+    retrieveQuery(model: Model): Query;
+    retrieve(model: Model, verify?: boolean): Promise<Model | null>;
+    titlesQuery(model: Model): Query;
+    titles(model: Model): Promise<Titles>;
+    updateQuery(model: Model): Query;
+    update(model: Model): Promise<number>;
+    deleteQuery(model: Model): Query;
+    delete(model: Model): Promise<number>;
+    definition(filePath: string, sourcePath: string): Promise<void>;
+    migration(filePath: string, sourcePath: string): Promise<void>;
+    execute(models: Stored | Stored[]): Promise<void>;
+    load(loadPath: string): Promise<void>;
+    list(sourcePath: string): Promise<globalThis.Record<string, any>>;
+    migrate(sourcePath: string): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=mock.d.ts.map