ultimabase 0.0.0-stage → 0.1.1

package/dist/identify.js

@@ -0,0 +1,71 @@
+// How a transport finds who sends a request (D-49, D-106, D-112): Master with
+// the master key, then the first plugin that knows it, anonymous otherwise.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { PublicError, Refused } from './errors.js';
+import { createMaster } from './rules.js';
+/** The header a transport reads the master key from. */
+export const masterKeyHeader = 'x-ultimabase-master-key';
+const anonymous = Object.freeze({ kind: 'anonymous' });
+const keyMaster = createMaster('key');
+// Digests have one length, so the comparison takes the same time for any key.
+const digest = (text) => createHash('sha256').update(text).digest();
+/** Why a request sending a key is refused before it is compared, if so. */
+function refusalOf(masterKey) {
+    const key = typeof masterKey === 'object' ? masterKey.key : masterKey;
+    // An empty variable is unset: an empty header must not open Master.
+    if (key === undefined || key === '')
+        return 'No master key is configured.';
+    if (process.env['NODE_ENV'] === 'production' &&
+        typeof masterKey !== 'object') {
+        return 'The master key is refused in production.';
+    }
+    return undefined;
+}
+/**
+ * Reads the master key and `NODE_ENV` once, when the application starts.
+ * `plugins` is read on each request: it is filled once their contexts exist.
+ * The caller a plugin knows is completed (D-121).
+ */
+export function identifier(masterKey, logger, plugins, complete) {
+    const refusal = refusalOf(masterKey);
+    const key = typeof masterKey === 'object' ? masterKey.key : masterKey;
+    // A header drops the spaces around a value and mangles what is not ASCII:
+    // such a key could never match.
+    if (key !== undefined && key !== '' && !/^[\x21-\x7e]+$/.test(key)) {
+        throw new Refused('The master key holds a space or a character outside ASCII, which a header cannot carry: use letters, digits and symbols only.');
+    }
+    const expected = digest(key ?? '');
+    // Outside production, the HTTP plugin's development log already shows
+    // each request (D-108); a use of the key is an audit line in production.
+    const audited = process.env['NODE_ENV'] === 'production';
+    // Nothing limits the keys a client tries: one that opens Master in
+    // production must not be guessed.
+    if (audited &&
+        refusal === undefined &&
+        key !== undefined &&
+        key.length < 32) {
+        throw new Refused(`The master key is ${key.length} characters long; production needs 32 at least: \`openssl rand -base64 32\` gives one.`);
+    }
+    return async (request) => {
+        const sent = request.headers.get(masterKeyHeader);
+        if (sent === null) {
+            for (const identify of plugins) {
+                const caller = await identify(request);
+                if (caller !== undefined)
+                    return complete(caller);
+            }
+            return anonymous;
+        }
+        const refused = refusal ??
+            (timingSafeEqual(digest(sent), expected)
+                ? undefined
+                : 'The master key is wrong.');
+        if (refused !== undefined) {
+            logger.warn(`A request sent the master key, refused: ${refused}`);
+            throw new PublicError('ACCESS_DENIED', refused);
+        }
+        if (audited)
+            logger.info('A request acts as Master with the master key.');
+        return keyMaster;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export type { Adapter, Aggregate, AggregateRead, Arithmetic, Change, Changed, Check, Condition, CountRead, Feed, Filter, GroupKey, ListUpdate, Migration, Migrations, Nested, Order, Read, Row, Run, ScalarType, Schema, SchemaField, SchemaModel, Sort, Statement, Stored, Transaction, Write, } from './adapter.ts';
+export { CheckFailed, feedFields, feedIds, MigrationFailed, OutOfRange, RelationViolation, UniqueViolation, } from './adapter.ts';
+export type { Logger, MasterKey } from './app-options.ts';
+export { defineApp } from './define-app.ts';
+export { defineEnum } from './define-enum.ts';
+export type { FieldShapes, ModelFields, ModelIndexes, ModelOf, } from './define-model.ts';
+export { defineModel } from './define-model.ts';
+export type { ErrorCode, Issue } from './errors.ts';
+export { InvalidQuery, PublicError, Refused } from './errors.ts';
+export type { DecimalOptions, Enum, Field, FieldBuilders, JsonOptions, JsonValue, ListOptions, Many, ManyOptions, One, ScalarOptions, SingleOptions, StringOptions, } from './fields.ts';
+export { defineFunction, defineType } from './define-function.ts';
+export type { FieldType, FieldTypeDefinition, FieldTypeOptions, } from './field-type.ts';
+export { defineFieldType } from './field-type.ts';
+export { isLocalHost } from './hosts.ts';
+export type { Client, CookieOptions, FunctionPlugin, FunctionShape, Nullable, ObjectType, OutputSpec, ServerFunction, } from './function.ts';
+export { memory } from './memory.ts';
+export type { App, FindOperation, IndexShape, Model } from './model.ts';
+export type { ExposedFunction, ExposedModel, ExposedOutput, ExposedVirtual, ExposedType, ModelQueries, ModelUse, OutputForm, PluginOf, PluginTypes, UseOf, } from './plugin.ts';
+export type { Payload, Queries } from './query.ts';
+export { definePlugin } from './plugin.ts';
+export type { Caller, CallerRule, Identity, Register, UserCallerKeys, UserOf, } from './rules.ts';
+export { allOf, allow, anyOf, isMaster, master } from './rules.ts';
+export { transaction } from './transaction.ts';
+export type { ArgsOf, CreateDataOf, IncludeOf, InputOf, OrderByOf, OutputOf, RecordOf, SelectOf, UpdateDataOf, WhereOf, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACX,OAAO,EACP,SAAS,EACT,aAAa,EACb,UAAU,EACV,MAAM,EACN,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,KAAK,EACL,IAAI,EACJ,GAAG,EACH,GAAG,EACH,UAAU,EACV,MAAM,EACN,WAAW,EACX,WAAW,EACX,IAAI,EACJ,SAAS,EACT,MAAM,EACN,WAAW,EACX,KAAK,GACL,MAAM,cAAc,CAAA;AACrB,OAAO,EACN,WAAW,EACX,UAAU,EACV,OAAO,EACP,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,eAAe,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,OAAO,GACP,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAChE,YAAY,EACX,cAAc,EACd,IAAI,EACJ,KAAK,EACL,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,IAAI,EACJ,WAAW,EACX,GAAG,EACH,aAAa,EACb,aAAa,EACb,aAAa,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjE,YAAY,EACX,SAAS,EACT,mBAAmB,EACnB,gBAAgB,GAChB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EACX,MAAM,EACN,aAAa,EACb,cAAc,EACd,aAAa,EACb,QAAQ,EACR,UAAU,EACV,UAAU,EACV,cAAc,GACd,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvE,YAAY,EACX,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,WAAW,EACX,KAAK,GACL,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EACX,MAAM,EACN,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,MAAM,GACN,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,YAAY,EACX,MAAM,EACN,YAAY,EACZ,SAAS,EACT,OAAO,EACP,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,OAAO,GACP,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export { CheckFailed, feedFields, feedIds, MigrationFailed, OutOfRange, RelationViolation, UniqueViolation, } from './adapter.js';
+export { defineApp } from './define-app.js';
+export { defineEnum } from './define-enum.js';
+export { defineModel } from './define-model.js';
+export { InvalidQuery, PublicError, Refused } from './errors.js';
+export { defineFunction, defineType } from './define-function.js';
+export { defineFieldType } from './field-type.js';
+export { isLocalHost } from './hosts.js';
+export { memory } from './memory.js';
+export { definePlugin } from './plugin.js';
+export { allOf, allow, anyOf, isMaster, master } from './rules.js';
+export { transaction } from './transaction.js';

package/dist/internal.d.ts

@@ -0,0 +1,28 @@
+import type { Adapter } from './adapter.ts';
+import type { Lifecycle } from './lifecycle.ts';
+export type { Lifecycle };
+export type { Scratch } from './scratch.ts';
+export { scratchable, scratchOf } from './scratch.ts';
+export { isRow } from './field-codec.ts';
+export { joining } from './transaction.ts';
+export { issueOf } from './write-data.ts';
+export { decimalPattern } from './decimal.ts';
+export type { Recorded } from './recorder.ts';
+export { recording } from './recorder.ts';
+export type { LivePlan } from './live.ts';
+export { inMemory, liveSchema, livePlan, matches, servedRows, sortKeys, storedRows, } from './live.ts';
+export { compareKeys } from './memory-values.ts';
+/** The application's database, and new runs of it on another (D-130). */
+export type QuietRuns = {
+    readonly declared: Adapter;
+    /** A run on `database`, without info lines. */
+    readonly on: (database: Adapter) => Lifecycle;
+};
+/**
+ * Runs of the application `defineApp` returned as `app`, or `undefined` for
+ * another value.
+ */
+export declare function quietRuns(app: unknown): QuietRuns | undefined;
+/** The running application's plugin API named `name`, if any. */
+export declare function runningApi(name: string): unknown;
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAI3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAI/C,YAAY,EAAE,SAAS,EAAE,CAAA;AACzB,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EACN,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,OAAO,EACP,UAAU,EACV,QAAQ,EACR,UAAU,GACV,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAYhD,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,SAAS,CAAA;CAC7C,CAAA;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAQ7D;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/internal.js

@@ -0,0 +1,39 @@
+import { internalsOf } from './app-internals.js';
+import { consoleLogger } from './console-logger.js';
+import { lifecycle } from './lifecycle.js';
+import { current } from './running.js';
+export { scratchable, scratchOf } from './scratch.js';
+export { isRow } from './field-codec.js';
+export { joining } from './transaction.js';
+export { issueOf } from './write-data.js';
+export { decimalPattern } from './decimal.js';
+export { recording } from './recorder.js';
+export { inMemory, liveSchema, livePlan, matches, servedRows, sortKeys, storedRows, } from './live.js';
+export { compareKeys } from './memory-values.js';
+/** `logger` without its info lines. */
+function quieted(logger) {
+    return {
+        info: () => undefined,
+        warn: logger.warn.bind(logger),
+        error: logger.error.bind(logger),
+        child: (bindings) => quieted(logger.child(bindings)),
+    };
+}
+/**
+ * Runs of the application `defineApp` returned as `app`, or `undefined` for
+ * another value.
+ */
+export function quietRuns(app) {
+    const options = internalsOf(app)?.options;
+    if (options === undefined)
+        return undefined;
+    const logger = quieted(options.logger ?? consoleLogger());
+    return {
+        declared: options.database,
+        on: (database) => lifecycle({ ...options, database, logger }),
+    };
+}
+/** The running application's plugin API named `name`, if any. */
+export function runningApi(name) {
+    return current()?.apis.get(name);
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,21 @@
+import type { Adapter, Schema } from './adapter.ts';
+import type { Logger, MasterKey } from './app-options.ts';
+export type Lifecycle = {
+    readonly start: () => Promise<void>;
+    readonly stop: () => Promise<void>;
+};
+export type LifecycleOptions = {
+    readonly database: Adapter;
+    readonly plugins?: readonly unknown[];
+    /** The application's `defineFunction` values (D-27). */
+    readonly functions?: readonly unknown[];
+    readonly models: readonly unknown[];
+    readonly logger?: Logger;
+    readonly masterKey?: MasterKey;
+};
+/** The application's schema, or a message on what is wrong with it. */
+export declare function schemaOf(options: LifecycleOptions): Schema;
+/** The kernel's logger: the application's, or JSON lines. */
+export declare const kernelLogger: (options: LifecycleOptions) => Logger;
+export declare function lifecycle(options: LifecycleOptions): Lifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAqBzD,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC,CAAA;AAuBD,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAC9B,CAAA;AAUD,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAM1D;AAED,6DAA6D;AAC7D,eAAO,MAAM,YAAY,YAAa,gBAAgB,KAAG,MACS,CAAA;AAkBlE,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAoH9D"}

package/dist/lifecycle.js

@@ -0,0 +1,149 @@
+import { completer } from './complete.js';
+import { consoleLogger } from './console-logger.js';
+import { feedOf } from './feed.js';
+import { identifier } from './identify.js';
+import { checkVersions } from './manifest.js';
+import { checked, synced } from './migrate.js';
+import { buildApis, installed, pluginCallers, pluginIdentifiers, withContexts, } from './plugin-app.js';
+import { register, unregister, Work } from './running.js';
+import { resolve } from './schema.js';
+/** Stops `plugins` in reverse order, each even when another fails. */
+async function stopped(plugins) {
+    const errors = [];
+    for (const { code, context } of plugins.toReversed()) {
+        if (code.stop === undefined)
+            continue;
+        try {
+            await Reflect.apply(code.stop, undefined, [context]);
+        }
+        catch (error) {
+            context.logger.error({ err: error }, 'The plugin failed to stop.');
+            errors.push(error);
+        }
+    }
+    return errors;
+}
+/** Once stdout and stderr have written what they were given. */
+const written = () => Promise.all([process.stdout, process.stderr].map((stream) => new Promise((done) => stream.write('', done))));
+/** The application's schema, or a message on what is wrong with it. */
+export function schemaOf(options) {
+    const { plugins } = installed(options.plugins ?? []);
+    return resolve(options.models, plugins.map((plugin) => plugin.code)).schema;
+}
+/** The kernel's logger: the application's, or JSON lines. */
+export const kernelLogger = (options) => (options.logger ?? consoleLogger()).child({ name: 'ultimabase' });
+/** Syncs a development database, or checks a production one (D-105). */
+async function follow(database, schema, logger) {
+    try {
+        await (process.env['NODE_ENV'] === 'production'
+            ? checked(database, schema, logger)
+            : synced(database, schema, logger, false));
+    }
+    catch (error) {
+        await database.stop();
+        throw error;
+    }
+}
+export function lifecycle(options) {
+    const { database, models } = options;
+    let started;
+    let stopping;
+    let starting = false;
+    const shutDown = async ({ app, plugins, onSigterm }) => {
+        process.off('SIGTERM', onSigterm);
+        const errors = await stopped(plugins);
+        // A plugin's stop may still query; the database closes last.
+        await app.work.settled();
+        unregister(app);
+        started = undefined;
+        await database.stop();
+        app.logger.info('Application stopped.');
+        if (errors.length > 0)
+            throw errors[0];
+    };
+    const stop = async () => {
+        if (stopping !== undefined)
+            return stopping;
+        if (started === undefined)
+            return;
+        stopping = shutDown(started).finally(() => {
+            stopping = undefined;
+        });
+        return stopping;
+    };
+    const start = async () => {
+        if (started !== undefined || starting) {
+            throw new Error('The application is running.');
+        }
+        // Set before the first await: a second start meanwhile is refused.
+        starting = true;
+        try {
+            await launch();
+        }
+        finally {
+            starting = false;
+        }
+    };
+    const launch = async () => {
+        const { plugins: records, apiOrder } = installed(options.plugins ?? []);
+        const resolved = resolve(models, records.map((plugin) => plugin.code));
+        const base = options.logger ?? consoleLogger();
+        const logger = base.child({ name: 'ultimabase' });
+        checkVersions(records, logger);
+        // Plugins identify with their contexts, which hold identify.
+        const identifiers = [];
+        const callers = [];
+        const complete = completer(callers);
+        const identify = identifier(options.masterKey, logger, identifiers, complete);
+        const { plugins, functions } = withContexts(apiOrder, base, identify, resolved, options.functions ?? []);
+        identifiers.push(...pluginIdentifiers(records, plugins));
+        callers.push(...pluginCallers(records, plugins));
+        await database.start(resolved.schema, logger, feedOf(records, plugins));
+        const apis = new Map();
+        const app = {
+            resolved,
+            adapter: database,
+            logger,
+            apis,
+            functions: functions.definitions,
+            work: new Work(),
+            complete,
+        };
+        const ran = [];
+        try {
+            await follow(database, resolved.schema, logger);
+            register(app);
+            // An API may read the APIs it needs as it is built (D-89).
+            buildApis(plugins, apis);
+            for (const plugin of plugins) {
+                const { code, context } = plugin;
+                if (code.start !== undefined) {
+                    await Reflect.apply(code.start, undefined, [context]);
+                }
+                ran.push(plugin);
+            }
+        }
+        catch (error) {
+            await stopped(ran);
+            unregister(app);
+            await database.stop();
+            throw error;
+        }
+        const onSigterm = () => {
+            void stop()
+                .catch((error) => {
+                logger.error({ err: error }, 'The application stopped with an error.');
+            })
+                // The last lines first: a pipe may write them later.
+                .then(written)
+                .finally(() => {
+                // Its listener is gone: the signal now ends the process.
+                process.kill(process.pid, 'SIGTERM');
+            });
+        };
+        process.once('SIGTERM', onSigterm);
+        started = { app, plugins, onSigterm };
+        logger.info('Application started.');
+    };
+    return { start, stop };
+}

package/dist/list-update.d.ts

@@ -0,0 +1,12 @@
+import type { ListUpdate } from './adapter.ts';
+import type { ModelInfo } from './schema.ts';
+import type { Draft } from './write-data.ts';
+/**
+ * Takes the operations out of an update's draft: `{ set }` becomes its
+ * list, an operation by `undefined` leaves its field as it is (D-84), and
+ * each other one comes back to be computed on the row.
+ */
+export declare function listUpdates(model: ModelInfo, draft: Draft, at?: readonly (string | number)[]): Map<string, ListUpdate>;
+/** A list update's result on `current`, the elements in their order. */
+export declare function listed(current: unknown, { operation, elements }: ListUpdate): unknown[];
+//# sourceMappingURL=list-update.d.ts.map

package/dist/list-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-update.d.ts","sourceRoot":"","sources":["../src/list-update.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAS5C;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,KAAK,EACZ,EAAE,GAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAO,GACnC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CA6BzB;AAED,wEAAwE;AACxE,wBAAgB,MAAM,CACrB,OAAO,EAAE,OAAO,EAChB,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,UAAU,GACjC,OAAO,EAAE,CAUX"}

package/dist/list-update.js

@@ -0,0 +1,52 @@
+import { InvalidQuery } from './errors.js';
+import { isObject } from './query-where.js';
+import { invalid, issueOf } from './write-data.js';
+const operations = ['set', 'push', 'pushUnique', 'remove'];
+const isOperation = (key) => operations.some((operation) => operation === key);
+/**
+ * Takes the operations out of an update's draft: `{ set }` becomes its
+ * list, an operation by `undefined` leaves its field as it is (D-84), and
+ * each other one comes back to be computed on the row.
+ */
+export function listUpdates(model, draft, at = []) {
+    const lists = new Map();
+    for (const [name, value] of Object.entries(draft)) {
+        const field = model.fields.get(name);
+        // A field type's value is its own, as for numbers (D-132).
+        const plain = field?.kind === 'scalar' && field.list && !field.codec;
+        if (!plain || !isObject(value))
+            continue;
+        const keys = Object.keys(value);
+        const used = operations.filter((key) => value[key] !== undefined);
+        if (keys.length === 0 || used.length > 1 || !keys.every(isOperation)) {
+            const path = ['data', ...at, name].join('.');
+            throw new InvalidQuery(path, `${path} takes a list or one of ${operations.join(', ')}.`);
+        }
+        delete draft[name];
+        const [operation] = used;
+        if (operation === undefined)
+            continue;
+        const given = value[operation];
+        const elements = Array.isArray(given) ? given : [given];
+        const issue = issueOf(elements, field);
+        if (issue !== undefined) {
+            throw invalid([{ path: [...at, name], message: issue }]);
+        }
+        if (operation === 'set')
+            draft[name] = elements;
+        else
+            lists.set(name, { operation, elements });
+    }
+    return lists;
+}
+/** A list update's result on `current`, the elements in their order. */
+export function listed(current, { operation, elements }) {
+    const from = Array.isArray(current) ? current : [];
+    if (operation === 'push')
+        return [...from, ...elements];
+    if (operation === 'remove') {
+        return from.filter((item) => !elements.includes(item));
+    }
+    const added = elements.filter((item, index) => !from.includes(item) && elements.indexOf(item) === index);
+    return [...from, ...added];
+}

package/dist/live.d.ts

@@ -0,0 +1,37 @@
+import type { Filter, Nested, Order, Row, Schema } from './adapter.ts';
+import type { Caller } from './rules.ts';
+/**
+ * The rows a live read follows, and their order, ending with `id`; `filter`
+ * is the read's own part of `where`, `rights` the part the caller's read
+ * rules and `beforeFind` add, and
+ * `include`, `count` and `fields` what its selection reads, as the adapter
+ * receives them.
+ */
+export type LivePlan = Pick<Nested, 'include' | 'count' | 'fields'> & {
+    readonly where: Filter | undefined;
+    readonly filter: Filter | undefined;
+    readonly rights: Filter | undefined;
+    readonly orderBy: readonly Order[];
+};
+/**
+ * `args` as `caller` reads `model`: its read rules and every `beforeFind`
+ * included. A live row's `where` names one row, as `findUnique`'s.
+ */
+export declare function livePlan(model: string, args: unknown, caller: Caller, row?: boolean): Promise<LivePlan>;
+/** The stored rows `read` finds, as Master, plugin fields undecoded. */
+export declare function storedRows(model: string, read: Nested): Promise<readonly Row[]>;
+/** The running application's schema, its plugins' models included. */
+export declare function liveSchema(): Schema;
+/** Whether `filter` reads `model`'s row alone, so `matches` can test it. */
+export declare function inMemory(model: string, filter: Filter | undefined): boolean;
+/** Whether the stored `row` of `model` passes `filter`, which `inMemory` takes. */
+export declare function matches(model: string, row: Row, filter: Filter | undefined): boolean;
+/**
+ * `findMany(args)` on `model` as `caller`, its rows taken from the stored
+ * `rows` when they alone answer it, else from the database. `rows` holds
+ * every row its `where` finds.
+ */
+export declare function servedRows(model: string, args: unknown, caller: Caller, rows: ReadonlyMap<string, Row>): Promise<readonly Row[]>;
+/** The sort keys of the stored `row`, for an order on its own fields. */
+export declare function sortKeys(model: string, row: Row, orderBy: readonly Order[]): unknown[];
+//# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAQ,GAAG,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAS5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAKxC;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC,GAAG;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,CAAA;CAClC,CAAA;AAYD;;;GAGG;AACH,wBAAsB,QAAQ,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,GAAG,UAAQ,GACT,OAAO,CAAC,QAAQ,CAAC,CA4BnB;AAED,wEAAwE;AACxE,wBAAsB,UAAU,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACV,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,CAGzB;AAED,sEAAsE;AACtE,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAY3E;AAkBD,mFAAmF;AACnF,wBAAgB,OAAO,CACtB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAET;AA4BD;;;;GAIG;AACH,wBAAsB,UAAU,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,CAYzB;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,SAAS,KAAK,EAAE,GACvB,OAAO,EAAE,CAQX"}

package/dist/live.js

@@ -0,0 +1,139 @@
+// What the realtime plugin asks the kernel (D-154): a live read's effective
+// filter and order, planned once for its caller, and, on a stored row, that
+// filter and the row's sort keys, tested as `memory()` reads.
+import { accessFor, and } from './access.js';
+import { rootFind } from './engine.js';
+import { decoded, isRow } from './field-codec.js';
+import { Reader } from './memory-read.js';
+import { compareKeys, sortable } from './memory-values.js';
+import { isFilters } from './memory-conditions.js';
+import { plan, uniqueWhere } from './query-args.js';
+import { modelOf } from './query-where.js';
+import { isObject } from './query-values.js';
+import { current } from './running.js';
+import { QueryScope, planned } from './scope.js';
+function started() {
+    const app = current();
+    if (app === undefined)
+        throw new Error('No application is running.');
+    return app;
+}
+const shapeKeys = ['select', 'include', 'omit'];
+const liveKeys = new Set(['where', 'orderBy', ...shapeKeys]);
+const rowKeys = new Set(shapeKeys);
+/**
+ * `args` as `caller` reads `model`: its read rules and every `beforeFind`
+ * included. A live row's `where` names one row, as `findUnique`'s.
+ */
+export async function livePlan(model, args, caller, row = false) {
+    const app = started();
+    const { models } = app.resolved;
+    const info = modelOf(models, model);
+    const access = accessFor(models, caller, app.logger);
+    const scope = new QueryScope(models, caller, access);
+    const { where: unique, ...shape } = isObject(args) ? args : {};
+    return app.work.run(async () => planned(scope, () => {
+        const { read } = row
+            ? plan(models, info, shape, '', 'many', rowKeys, scope)
+            : plan(models, info, args, '', 'many', liveKeys, scope);
+        const rights = scope.readable(model);
+        const where = row
+            ? uniqueWhere(models, info, unique, 'where', scope)
+            : read.where;
+        const { include, count, fields } = read;
+        return {
+            ...(include && { include }),
+            ...(count && { count }),
+            ...(fields && { fields }),
+            where: and(where, rights),
+            filter: where,
+            rights,
+            orderBy: read.orderBy ?? [{ field: 'id', direction: 'asc' }],
+        };
+    }));
+}
+/** The stored rows `read` finds, as Master, plugin fields undecoded. */
+export async function storedRows(model, read) {
+    const app = started();
+    return app.work.run(async () => app.adapter.find({ ...read, model }));
+}
+/** The running application's schema, its plugins' models included. */
+export function liveSchema() {
+    return started().resolved.schema;
+}
+/** Whether `filter` reads `model`'s row alone, so `matches` can test it. */
+export function inMemory(model, filter) {
+    const fields = modelOf(started().resolved.models, model).fields;
+    return Object.entries(filter ?? {}).every(([key, value]) => {
+        if (value === undefined)
+            return true;
+        if (isFilters(value))
+            return value.every((part) => inMemory(model, part));
+        // A search ranks as each database does (D-148).
+        if (value.search !== undefined || value.removedBy !== undefined) {
+            return false;
+        }
+        const field = fields.get(key);
+        return field === undefined || field.kind === 'scalar';
+    });
+}
+const readers = new WeakMap();
+function readerOf(app) {
+    const known = readers.get(app);
+    if (known !== undefined)
+        return known;
+    const fields = new Map(app.resolved.schema.models.map((model) => [
+        model.name,
+        new Map(model.fields.map((field) => [field.name, field])),
+    ]));
+    const reader = new Reader({ tables: new Map(), joins: new Map() }, fields);
+    readers.set(app, reader);
+    return reader;
+}
+/** Whether the stored `row` of `model` passes `filter`, which `inMemory` takes. */
+export function matches(model, row, filter) {
+    return readerOf(started()).matches(model, row, filter) === true;
+}
+/** Whether rows alone answer `read`: one level, unpaged, read in memory. */
+const servable = (read) => read.include === undefined &&
+    read.count === undefined &&
+    read.distinct === undefined &&
+    read.cursor === undefined &&
+    read.skip === undefined &&
+    read.take === undefined &&
+    (read.orderBy ?? []).every((order) => (order.through ?? order.count ?? order.relevance) === undefined) &&
+    inMemory(read.model, read.where);
+/**
+ * The stored `rows` that pass `read`, in its order; the find that asked for
+ * them keeps the fields its shape selects.
+ */
+function served(read, rows) {
+    const { model, orderBy = [] } = read;
+    const kept = [...rows].filter((row) => matches(model, row, read.where));
+    const keys = new Map(kept.map((row) => [row, sortKeys(model, row, orderBy)]));
+    const key = (row) => keys.get(row) ?? [];
+    kept.sort((a, b) => compareKeys(key(a), key(b), orderBy));
+    return kept;
+}
+/**
+ * `findMany(args)` on `model` as `caller`, its rows taken from the stored
+ * `rows` when they alone answer it, else from the database. `rows` holds
+ * every row its `where` finds.
+ */
+export async function servedRows(model, args, caller, rows) {
+    const { models } = started().resolved;
+    const found = await rootFind(model, args, { as: caller }, async (store, read) => servable(read)
+        ? decoded(models, read, served(read, rows.values()))
+        : store.find(read));
+    return Array.isArray(found) ? found.filter(isRow) : [];
+}
+/** The sort keys of the stored `row`, for an order on its own fields. */
+export function sortKeys(model, row, orderBy) {
+    const reader = readerOf(started());
+    return orderBy.map((order) => {
+        if (order.through ?? order.count ?? order.relevance) {
+            throw new Error(`The order by ${order.field} reads another row.`);
+        }
+        return sortable(row[order.field] ?? null, reader.field(model, order.field));
+    });
+}

package/dist/manifest.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from './app-options.ts';
+import type { PluginRecord } from './definition.ts';
+import type { Manifest } from './plugin.ts';
+/** Checks a plugin's `manifest`: a name, a version and valid ranges. */
+export declare function manifestOf(value: unknown, plugin: string): Manifest;
+/**
+ * Refuses a plugin whose ranges exclude the running kernel or an installed
+ * plugin, naming both versions; warns of one that gives the kernel no range.
+ */
+export declare function checkVersions(plugins: readonly PluginRecord[], logger: Logger): void;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAI3C,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CA4BnE;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,MAAM,EAAE,MAAM,GACZ,IAAI,CAkBN"}