ultimabase 0.0.0-stage → 0.1.0

package/dist/plugin-code.d.ts

@@ -0,0 +1,17 @@
+import type { PluginCode } from './definition.ts';
+/** The fixed hooks of D-15. */
+export declare const hookNames: readonly ['beforeFind', 'beforeCreate', 'beforeUpdate', 'beforeDelete', 'afterCreate', 'afterUpdate', 'afterDelete', 'afterCreateCommit', 'afterUpdateCommit', 'afterDeleteCommit'];
+/** Checks what a plugin's author wrote; the types refuse the rest. */
+export declare function pluginCode(definition: unknown): PluginCode;
+export type Command = {
+    readonly model: string;
+    readonly plugin: string;
+    readonly command: string;
+};
+/** The command of `plugin` running on `model`, if any (D-89). */
+export declare function commandOf(model: string, plugin: string): string | undefined;
+/** Runs `run` as `plugin`'s command `command` on `model`. */
+export declare function inCommand<R>(command: Command, run: () => R): R;
+/** Runs a hook's body: the queries it makes run outside any command. */
+export declare function outsideCommands<R>(run: () => R): R;
+//# sourceMappingURL=plugin-code.d.ts.map

package/dist/plugin-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-code.d.ts","sourceRoot":"","sources":["../src/plugin-code.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAyBlE,+BAA+B;AAC/B,eAAO,MAAM,SAAS,YACrB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,CACV,CAAA;AAgDV,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,UAAU,EAAE,OAAO,GAAG,UAAU,CA0C1D;AAED,MAAM,MAAM,OAAO,GAAG;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB,CAAA;AAID,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK3E;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAE9D;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAElD"}

package/dist/plugin-code.js

@@ -0,0 +1,125 @@
+// A plugin's code at run time (D-57, D-89): what `definePlugin` checks, the
+// APIs it reads once the application starts, and the command it runs in.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { nameOf } from './definition.js';
+import { manifestOf } from './manifest.js';
+import { isObject } from './query-where.js';
+import { current } from './running.js';
+function functionAt(holder, key, path) {
+    const value = holder[key];
+    if (value === undefined || typeof value === 'function')
+        return value;
+    throw new TypeError(`${path} is a function.`);
+}
+function objectAt(holder, key, path) {
+    const value = holder[key];
+    if (value === undefined)
+        return {};
+    if (!isObject(value))
+        throw new TypeError(`${path} is an object.`);
+    return value;
+}
+/** The fixed hooks of D-15. */
+export const hookNames = [
+    'beforeFind',
+    'beforeCreate',
+    'beforeUpdate',
+    'beforeDelete',
+    'afterCreate',
+    'afterUpdate',
+    'afterDelete',
+    'afterCreateCommit',
+    'afterUpdateCommit',
+    'afterDeleteCommit',
+];
+/** The APIs of `names`, each read from the running application. */
+function apisOf(plugin, names) {
+    const plugins = {};
+    for (const name of names) {
+        Object.defineProperty(plugins, name, {
+            enumerable: true,
+            get: () => {
+                const app = current();
+                if (app === undefined) {
+                    throw new Error(`${plugin}: plugins.${name} is read once the application starts.`);
+                }
+                return app.apis.get(name);
+            },
+        });
+    }
+    return Object.freeze(plugins);
+}
+const isList = (value) => Array.isArray(value);
+/** `addedIndexes`, each `{ fields, unique?, contains? }`; startup checks the fields. */
+function indexesOf(value, path) {
+    const indexes = value ?? [];
+    const valid = (index) => isObject(index) &&
+        isList(index['fields']) &&
+        index['fields'].every((field) => typeof field === 'string') &&
+        (index['unique'] === undefined || typeof index['unique'] === 'boolean') &&
+        (index['contains'] === undefined || index['contains'] === true);
+    if (!isList(indexes) || !indexes.every(valid)) {
+        throw new TypeError(`${path} is a list of { fields, unique?, contains?: true }.`);
+    }
+    return Object.freeze(indexes.map(({ fields, unique, contains }) => ({
+        fields: [...fields],
+        ...(unique === undefined ? {} : { unique }),
+        ...(contains === undefined ? {} : { contains }),
+    })));
+}
+/** Checks what a plugin's author wrote; the types refuse the rest. */
+export function pluginCode(definition) {
+    if (!isObject(definition))
+        throw new TypeError('definePlugin takes an object.');
+    const name = nameOf(definition['name'], 'definePlugin');
+    const requires = Object.keys(objectAt(definition, 'requires', `${name}.requires`));
+    const optional = Object.keys(objectAt(definition, 'optional', `${name}.optional`));
+    const given = objectAt(definition, 'hooks', `${name}.hooks`);
+    const hooks = {};
+    for (const hook of hookNames) {
+        hooks[hook] = functionAt(given, hook, `${name}.hooks.${hook}`);
+    }
+    const redirect = objectAt(definition, 'redirect', `${name}.redirect`);
+    const part = (key) => functionAt(definition, key, `${name}.${key}`);
+    const models = definition['models'] ?? [];
+    if (!isList(models)) {
+        throw new TypeError(`${name}.models is an array.`);
+    }
+    return Object.freeze({
+        name,
+        manifest: manifestOf(definition['manifest'], name),
+        requires,
+        optional,
+        hooks: Object.freeze(hooks),
+        redirect: functionAt(redirect, 'delete', `${name}.redirect.delete`),
+        commands: part('commands'),
+        api: part('api'),
+        addedFields: part('addedFields'),
+        addedIndexes: indexesOf(definition['addedIndexes'], `${name}.addedIndexes`),
+        start: part('start'),
+        stop: part('stop'),
+        identify: part('identify'),
+        caller: part('caller'),
+        changed: part('changed'),
+        missed: part('missed'),
+        functions: part('functions'),
+        models: Object.freeze([...models]),
+        plugins: apisOf(name, [...requires, ...optional]),
+    });
+}
+const commands = new AsyncLocalStorage();
+/** The command of `plugin` running on `model`, if any (D-89). */
+export function commandOf(model, plugin) {
+    const running = commands.getStore();
+    return running?.model === model && running.plugin === plugin
+        ? running.command
+        : undefined;
+}
+/** Runs `run` as `plugin`'s command `command` on `model`. */
+export function inCommand(command, run) {
+    return commands.run(command, run);
+}
+/** Runs a hook's body: the queries it makes run outside any command. */
+export function outsideCommands(run) {
+    return commands.exit(run);
+}

package/dist/plugin-use.d.ts

@@ -0,0 +1,22 @@
+import type { FieldDefinition, IndexDefinition, ModelDefinition, PluginCode, PluginRecord, PluginUse } from './definition.ts';
+/**
+ * Adds the fields a `fields` callback, or a plugin's `addedFields`, built.
+ * `owners` names the plugin that added each field.
+ */
+export declare function addFields(model: string, built: unknown, fields: Map<string, FieldDefinition>, owners: Map<string, string>, plugin?: string): void;
+/**
+ * Reads a model's `use`: each entry once, the fields its plugins add into
+ * `fields`, and their commands, built with `queries`.
+ */
+/** The plugin entries `use` lists, each once (D-27). */
+export declare function entriesOf(name: string, use: unknown): readonly PluginRecord[];
+export declare function usedBy(model: string, use: readonly unknown[], fields: Map<string, FieldDefinition>, queries: object): {
+    readonly uses: readonly PluginUse[];
+    readonly commands: ReadonlyMap<string, unknown>;
+    readonly indexes: readonly IndexDefinition[];
+};
+/** Stops startup when `owner` uses a plugin that `plugins` does not hold. */
+export declare function checkInstalled(owner: string, code: PluginCode, plugins: readonly PluginCode[]): void;
+/** A model's plugins in the order of `plugins`, each one installed. */
+export declare function installedUses(definition: ModelDefinition, plugins: readonly PluginCode[]): readonly PluginUse[];
+//# sourceMappingURL=plugin-use.d.ts.map

package/dist/plugin-use.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-use.d.ts","sourceRoot":"","sources":["../src/plugin-use.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,eAAe,EACf,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,SAAS,EACT,MAAM,iBAAiB,CAAA;AAkBxB;;;GAGG;AACH,wBAAgB,SAAS,CACxB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACpC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,MAAM,CAAC,EAAE,MAAM,GACb,IAAI,CAyBN;AA0DD;;;GAGG;AACH,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,CAc7E;AAED,wBAAgB,MAAM,CACrB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS,OAAO,EAAE,EACvB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACpC,OAAO,EAAE,MAAM,GACb;IACF,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;CAC5C,CAyBA;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,SAAS,UAAU,EAAE,GAC5B,IAAI,CASN;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAC5B,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,SAAS,UAAU,EAAE,GAC5B,SAAS,SAAS,EAAE,CAmBtB"}

package/dist/plugin-use.js

@@ -0,0 +1,161 @@
+import { fieldBuilders, fieldDefinitions, pluginEntries } from './definition.js';
+import { inCommand } from './plugin-code.js';
+import { isObject, systemFields } from './query-where.js';
+import { Refused } from './errors.js';
+/** The kernel's names, which a model's field cannot take (D-22, D-20, D-134, D-148). */
+const reserved = new Set([
+    ...systemFields,
+    'AND',
+    'OR',
+    'NOT',
+    '_count',
+    '_search',
+    '_relevance',
+]);
+/**
+ * Adds the fields a `fields` callback, or a plugin's `addedFields`, built.
+ * `owners` names the plugin that added each field.
+ */
+export function addFields(model, built, fields, owners, plugin) {
+    if (!isObject(built)) {
+        const part = plugin === undefined ? 'fields' : `${plugin}.addedFields`;
+        throw new Refused(`${model}: ${part} must return an object of fields.`);
+    }
+    for (const [field, value] of Object.entries(built)) {
+        const recorded = typeof value === 'object' && value !== null
+            ? fieldDefinitions.get(value)
+            : undefined;
+        if (recorded === undefined) {
+            throw new Refused(`${model}.${field} is not a field a builder returned.`);
+        }
+        if (reserved.has(field)) {
+            throw new Refused(`${model}.${field}: the kernel owns this name.`);
+        }
+        if (plugin !== undefined && fields.has(field)) {
+            const owner = owners.get(field) ?? model;
+            throw new Refused(`${model}.${field}: ${plugin} adds a field ${owner} already has.`);
+        }
+        fields.set(field, recorded);
+        if (plugin !== undefined)
+            owners.set(field, plugin);
+    }
+}
+/** Runs a command's function, or each function of its object, as it. */
+function wrapped(value, command, path) {
+    const run = (fn) => (...args) => inCommand(command, () => {
+        const result = Reflect.apply(fn, undefined, args);
+        return result;
+    });
+    if (typeof value === 'function')
+        return run(value);
+    const refused = new TypeError(`${path} is a function or an object of functions.`);
+    if (!isObject(value))
+        throw refused;
+    const functions = {};
+    for (const [key, fn] of Object.entries(value)) {
+        if (typeof fn !== 'function')
+            throw refused;
+        functions[key] = run(fn);
+    }
+    return Object.freeze(functions);
+}
+function commandsOf(model, uses, methods) {
+    const commands = new Map();
+    const owners = new Map();
+    for (const { code, model: given } of uses) {
+        if (code.commands === undefined)
+            continue;
+        const built = Reflect.apply(code.commands, undefined, [given]);
+        if (!isObject(built)) {
+            throw new TypeError(`${code.name}.commands returns an object.`);
+        }
+        for (const [command, value] of Object.entries(built)) {
+            const path = `${model}.${command}`;
+            if (methods.has(command)) {
+                throw new Refused(`${path}: ${code.name} adds a command named after a model method.`);
+            }
+            const other = owners.get(command);
+            if (other !== undefined) {
+                throw new Refused(`${path}: ${other} and ${code.name} both add this command.`);
+            }
+            owners.set(command, code.name);
+            const running = { model, plugin: code.name, command };
+            commands.set(command, wrapped(value, running, path));
+        }
+    }
+    return commands;
+}
+/**
+ * Reads a model's `use`: each entry once, the fields its plugins add into
+ * `fields`, and their commands, built with `queries`.
+ */
+/** The plugin entries `use` lists, each once (D-27). */
+export function entriesOf(name, use) {
+    if (!Array.isArray(use))
+        throw new Refused(`${name}.use is a list.`);
+    const entries = [];
+    for (const value of use) {
+        const entry = isObject(value) ? pluginEntries.get(value) : undefined;
+        if (entry === undefined) {
+            throw new Refused(`${name}.use lists a value no plugin's entry returned.`);
+        }
+        if (entries.some((other) => other.code.name === entry.code.name)) {
+            throw new Refused(`${name}.use lists ${entry.code.name} twice.`);
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+export function usedBy(model, use, fields, queries) {
+    const uses = [];
+    const owners = new Map();
+    for (const { code, options } of entriesOf(model, use)) {
+        if (code.addedFields !== undefined) {
+            const built = Reflect.apply(code.addedFields, undefined, [
+                fieldBuilders,
+                options,
+            ]);
+            addFields(model, built, fields, owners, code.name);
+        }
+        const given = { name: model, queries, options, plugins: code.plugins };
+        uses.push({ code, model: Object.freeze(given) });
+    }
+    const redirecting = uses.filter((each) => each.code.redirect !== undefined);
+    if (redirecting.length > 1) {
+        const names = redirecting.map((each) => each.code.name).join(' and ');
+        throw new Refused(`${model}: ${names} both redirect delete.`);
+    }
+    const methods = new Set(['name', 'with', 'nullable', ...Object.keys(queries)]);
+    return {
+        uses,
+        commands: commandsOf(model, uses, methods),
+        indexes: uses.flatMap(({ code }) => code.addedIndexes),
+    };
+}
+/** Stops startup when `owner` uses a plugin that `plugins` does not hold. */
+export function checkInstalled(owner, code, plugins) {
+    if (plugins.includes(code))
+        return;
+    const { name } = code;
+    const other = plugins.some((each) => each.name === name);
+    throw new Refused(other
+        ? `${owner} uses a ${name} from another definePlugin than the one in plugins.`
+        : `${owner} uses ${name}, which is not in plugins.`);
+}
+/** A model's plugins in the order of `plugins`, each one installed. */
+export function installedUses(definition, plugins) {
+    const at = (use) => plugins.indexOf(use.code);
+    for (const use of definition.uses) {
+        checkInstalled(definition.name, use.code, plugins);
+    }
+    // A field type's plugin runs its hooks on the model, as if used (D-152).
+    const { name, queries } = definition;
+    const implicit = plugins
+        .filter((code) => !definition.uses.some((use) => use.code === code))
+        .filter((code) => [...definition.fields.values()].some((field) => field.kind === 'scalar' && field.codec?.plugin === code.name))
+        .map((code) => {
+        const model = { name, queries, options: {}, plugins: code.plugins };
+        return { code, model: Object.freeze(model) };
+    });
+    return [...definition.uses, ...implicit].toSorted((a, b) => at(a) - at(b));
+}