ultimabase 0.0.0-stage → 0.1.0

package/dist/writes.js

@@ -0,0 +1,246 @@
+// `create`, `update` and `delete` in the order of D-67: access rules on the
+// data sent, defaults, validation, `before*` hooks, the required check, the
+// write, which a plugin's `redirect` may replace (D-89), `after*` hooks; the
+// `*Commit` hooks once it commits (D-71, D-88). The row a write decides from
+// is locked; a write that loads none answers from the rows it changed (D-99,
+// D-104).
+import { and, recordOf } from './access.js';
+import { cascadeWhere } from './cascade.js';
+import { deleted } from './delete-many.js';
+import { PublicError } from './errors.js';
+import { redirectOf, rereads, runHook, settle, settles } from './hooks.js';
+import { first, given, hiddenBy, picked } from './query-context.js';
+import { project } from './query-project.js';
+import { computeVirtuals } from './virtual-read.js';
+import { oneKeys, plan, uniqueWhere } from './query-args.js';
+import { computeOn, operationsOf, inRange, validates } from './number-update.js';
+import { nests, resolveData } from './nested-write.js';
+import { createPlan, updatePlan } from './query-write.js';
+import { planned } from './scope.js';
+import { prepared, readData } from './write-data.js';
+import { updated } from './write-plan.js';
+import { uuidv7 } from './uuid.js';
+import { guarded, target } from './write-target.js';
+import { writingOf } from './writing.js';
+import { byId } from './query-where.js';
+/** The shape a single-row write returns, and each row of a bulk one's (D-149). */
+export async function returned(context, found) {
+    const { models, model, scope } = context;
+    return planned(scope, () => plan(models, model, picked(found), '', 'one', oneKeys, scope));
+}
+/**
+ * Runs the plan, then the `after*` hooks. The written row comes back even
+ * when a read rule or `beforeFind` would hide it (D-86, D-88).
+ */
+async function written(context, store, commits, steps, events, at, checks = []) {
+    const { model, scope } = context;
+    const writing = writingOf(scope, store, events, checks);
+    // The rows it creates, after the row written, before the rows it moves.
+    events.push(...steps.events);
+    await steps.check(writing);
+    const changes = await steps.changes(writing);
+    const read = { model: model.name, ...at.read, where: byId(at.id) };
+    const again = rereads(events);
+    const write = {
+        checks: checks.map(({ check }) => check),
+        changes,
+        ...(again ? {} : { read }),
+    };
+    // Nothing follows a write without hooks: it may need no transaction.
+    const run = settles(events) ? store.write(write) : store.last(write);
+    const rows = await guarded(run, checks);
+    await settle(store, scope.caller, events, commits);
+    // An `after*` hook may have changed the rows: read them again (D-88).
+    const result = again ? await store.find(read) : rows;
+    return first(context, store, result, at.shape, scope.access);
+}
+/** Creates the row of `draft` as the rules allow. */
+async function creating(context, store, commits, draft, at) {
+    const { model, caller, scope } = context;
+    const { read, shape } = at;
+    const made = uuidv7();
+    const reach = { scope, reads: store, model, id: made, at: [] };
+    await resolveData({ ...reach, creating: true, trusted: false }, draft);
+    const sent = { ...draft };
+    scope.access?.allow(model, 'create', { data: sent });
+    await prepared(model, draft, caller, true);
+    await runHook(model, 'beforeCreate', { caller, data: draft });
+    const { id, plan: steps } = await createPlan(scope, model, draft, sent, store, made);
+    const events = [{ model, operation: 'create', id }];
+    return written(context, store, commits, steps, events, { id, read, shape });
+}
+export async function create(context, store, commits, args) {
+    const { models, model } = context;
+    const found = given(args, model.name, ['data', ...oneKeys], ['data']);
+    const at = await returned(context, found);
+    const draft = readData(models, model, found.get('data'), true);
+    return creating(context, store, commits, draft, at);
+}
+/**
+ * The rows a single-row write may target: the caller reads them (D-72), and
+ * the `beforeFind` hooks let it `operation` them (D-124).
+ */
+async function targets(context, found, operation) {
+    const { models, model, scope } = context;
+    return planned(scope, () => and(uniqueWhere(models, model, found.get('where'), 'where', scope), scope.readable(model.name, operation)));
+}
+const missing = (model) => `No ${model} matches.`;
+/** The `id` a unique `where` gives, if any. */
+function idOf(where) {
+    if (typeof where !== 'object' || where === null || !('id' in where)) {
+        return undefined;
+    }
+    return typeof where.id === 'string' ? where.id : undefined;
+}
+/**
+ * Updates the locked `row` as the rules allow; its number and list updates
+ * are computed on it first, so the rules and hooks see the results (D-132,
+ * D-149).
+ */
+async function updating(context, store, commits, data, at) {
+    const { model, caller, scope } = context;
+    const { row, read, shape } = at;
+    const { draft, operations } = data;
+    computeOn(model, row, draft, operations);
+    const reach = { scope, reads: store, model, id: row.id, at: [] };
+    await resolveData({ ...reach, creating: false, trusted: false }, draft);
+    const sent = { ...draft };
+    scope.access?.allow(model, 'update', { record: row, data: sent });
+    await prepared(model, draft, caller, false);
+    const record = recordOf(model, row);
+    await runHook(model, 'beforeUpdate', { caller, record, data: draft });
+    const steps = await updatePlan(scope, model, row.id, draft, sent, store);
+    const events = [
+        { model, operation: 'update', id: row.id, before: row },
+    ];
+    const to = { id: row.id, read, shape };
+    return written(context, store, commits, steps, events, to);
+}
+export async function update(context, store, commits, args) {
+    const { models, model, caller, scope } = context;
+    const found = given(args, model.name, ['where', 'data', ...oneKeys], ['where', 'data']);
+    const { read, shape } = await returned(context, found);
+    // The data's shape is checked whether or not the row is found.
+    const draft = readData(models, model, found.get('data'), false);
+    const operations = operationsOf(model, draft);
+    const id = idOf(found.get('where'));
+    const where = await targets(context, found, 'update');
+    if (scope.access === undefined &&
+        id !== undefined &&
+        !updated(model) &&
+        !nests(model, draft) &&
+        !validates(model, operations)) {
+        // Nothing needs the stored row: a check stands for its read (D-99),
+        // and the write computes its numbers and lists (D-132, D-149).
+        const sent = { ...draft };
+        await prepared(model, draft, caller, false);
+        const steps = await updatePlan(scope, model, id, draft, sent, store, operations);
+        const check = { model: model.name, where, count: 1, lock: true };
+        const message = missing(model.name);
+        const at = { id, read, shape };
+        const checks = [{ check, message }];
+        const result = await inRange(model, written(context, store, commits, steps, [], at, checks));
+        // The row went between the write's check and its change (D-104).
+        if (result === null)
+            throw new PublicError('NOT_FOUND', message);
+        return result;
+    }
+    const row = await target(context, store, where);
+    const data = { draft, operations };
+    return updating(context, store, commits, data, { row, read, shape });
+}
+export async function remove(context, store, commits, args) {
+    const { models, model, scope } = context;
+    const found = given(args, model.name, ['where', ...oneKeys], ['where']);
+    const { read, shape } = await returned(context, found);
+    const where = await targets(context, found, 'delete');
+    // Its relations, counts and virtuals, as the caller reads them, before
+    // the delete removes any: one read in its transaction (D-135, D-151).
+    const reaches = shape.relations.size > 0 ||
+        shape.counts.length > 0 ||
+        shape.virtuals.size > 0;
+    const shaped = async (by, lock) => {
+        if (!reaches)
+            return undefined;
+        const rows = await store.find({
+            model: model.name,
+            ...read,
+            where: by,
+            take: 1,
+            lock,
+        });
+        return rows[0];
+    };
+    const reach = cascadeWhere(models, model, where);
+    if (reach !== undefined && scope.access === undefined) {
+        const kept = await shaped(where, true);
+        const computed = await computeVirtuals(context, store, kept === undefined ? [] : [kept], shape, undefined);
+        // Nothing needs the stored row: a check stands for its read, and the
+        // write returns it as its delete removed it (D-102, D-104).
+        const check = { model: model.name, where, count: 1, lock: true };
+        const checks = [{ check, message: missing(model.name) }];
+        checks.push(...reach.checks);
+        const rows = await guarded(store.last({
+            checks: checks.map((each) => each.check),
+            changes: reach.changes,
+            read: { model: model.name, where, take: 1 },
+            before: true,
+        }), checks);
+        // Another transaction removed it meanwhile (D-104).
+        if (rows.length === 0)
+            throw new PublicError('NOT_FOUND', missing(model.name));
+        return project(kept ?? rows[0], shape, undefined, computed);
+    }
+    const row = await target(context, store, where);
+    scope.access?.allow(model, 'delete', { record: row });
+    const redirected = redirectOf(model) !== undefined;
+    // A redirected row stays: it is read as the redirect left it (D-89).
+    const kept = redirected ? undefined : await shaped(byId(row.id), false);
+    const hidden = hiddenBy(scope.access);
+    const before = redirected
+        ? undefined
+        : await computeVirtuals(context, store, [kept ?? row], shape, hidden);
+    await deleted(context, store, commits, [row]);
+    // The row as the redirect left it, or as it was once gone (D-89).
+    const [left] = redirected
+        ? await store.find({
+            model: model.name,
+            ...read,
+            where: byId(row.id),
+            take: 1,
+        })
+        : [kept];
+    const result = left ?? row;
+    const computed = before ?? (await computeVirtuals(context, store, [result], shape, hidden));
+    return project(result, shape, hidden, computed);
+}
+/**
+ * Updates the row `where` targets, or creates it when the caller finds
+ * none: the branch that runs is a plain update or create (D-142).
+ */
+export async function upsert(context, store, commits, args) {
+    const { models, model } = context;
+    const found = given(args, model.name, ['where', 'create', 'update', ...oneKeys], ['where', 'create', 'update']);
+    const at = await returned(context, found);
+    // Both data are checked, whichever runs.
+    const creation = readData(models, model, found.get('create'), true);
+    const draft = readData(models, model, found.get('update'), false);
+    const operations = operationsOf(model, draft);
+    const where = await targets(context, found, 'update');
+    const [row] = await store.find({
+        model: model.name,
+        where,
+        take: 1,
+        lock: true,
+    });
+    // Another create of the row meanwhile fails on its unique index.
+    if (row === undefined) {
+        return {
+            row: await creating(context, store, commits, creation, at),
+            created: true,
+        };
+    }
+    const data = { draft, operations };
+    const changed = await updating(context, store, commits, data, { row, ...at });
+    return { row: changed, created: false };
+}

package/dist/writing.d.ts

@@ -0,0 +1,10 @@
+import type { Change } from './adapter.ts';
+import type { Cascade } from './cascade.ts';
+import type { Event } from './hooks.ts';
+import type { QueryScope } from './scope.ts';
+import type { Store } from './transaction.ts';
+import type { Checked, Writing } from './write-plan.ts';
+/** The changes and events of a delete's cascade, its hooks run (D-90). */
+export declare function cascaded(writing: Writing, cascade: Cascade): Promise<Change[]>;
+export declare function writingOf(scope: QueryScope, store: Store, events: Event[], checks?: Checked[]): Writing;
+//# sourceMappingURL=writing.d.ts.map

package/dist/writing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writing.d.ts","sourceRoot":"","sources":["../src/writing.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAQ,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAI7D,0EAA0E;AAC1E,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BnB;AA4BD,wBAAgB,SAAS,CACxB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,KAAK,EAAE,EACf,MAAM,GAAE,OAAO,EAAO,GACpB,OAAO,CAWT"}

package/dist/writing.js

@@ -0,0 +1,66 @@
+// What one write's changes are made in (write-plan.ts): the rows a move's
+// hooks update planned again, and deletes run with their cascade and hooks
+// (D-88, D-90, D-138).
+import { recordOf } from './access.js';
+import { cascadeOf } from './cascade.js';
+import { InvalidQuery } from './errors.js';
+import { redirectOf, runHook } from './hooks.js';
+import { updatePlan } from './query-write.js';
+import { moved } from './write-plan.js';
+import { modelOf } from './query-where.js';
+/** The changes and events of a delete's cascade, its hooks run (D-90). */
+export async function cascaded(writing, cascade) {
+    const { caller } = writing.scope;
+    const changes = [];
+    for (const { model, field, rows } of cascade.nulled) {
+        const step = { model: model.name, field, to: null };
+        changes.push(...(await moved(step, model, rows, writing)));
+    }
+    for (const { model, row } of cascade.deleted) {
+        await runHook(model, 'beforeDelete', {
+            caller,
+            record: recordOf(model, row),
+        });
+    }
+    const ids = new Map();
+    for (const { model, row, redirected } of cascade.deleted) {
+        const redirect = redirected ? redirectOf(model) : undefined;
+        // Its queries run their own pipeline, in this transaction (D-89).
+        if (redirect !== undefined)
+            await redirect(caller, row.id);
+        else
+            ids.set(model.name, [...(ids.get(model.name) ?? []), row.id]);
+    }
+    for (const [model, deleted] of ids) {
+        changes.push({ kind: 'delete', model, where: { id: { in: deleted } } });
+    }
+    for (const { model, row } of cascade.deleted) {
+        writing.events.push({ model, operation: 'delete', id: row.id, before: row });
+    }
+    return changes;
+}
+/**
+ * A nested delete as `Target.delete` runs it: a plugin's redirect, or the
+ * cascade, which may not reach a row the write updates (D-138).
+ */
+async function dropped(writing, step) {
+    const { scope, store } = writing;
+    const model = modelOf(scope.models, step.model);
+    const cascade = await cascadeOf(scope.models, model, step.rows, store, step.except);
+    const reached = cascade.deleted.some(({ model: from, row }) => step.written.has(`${from.name}:${row.id}`));
+    if (reached) {
+        throw new InvalidQuery(step.path, `${step.path} deletes a row the write updates.`);
+    }
+    return cascaded(writing, cascade);
+}
+export function writingOf(scope, store, events, checks = []) {
+    const writing = {
+        store,
+        scope,
+        events,
+        checks,
+        replan: async (model, id, draft) => updatePlan(scope, model, id, draft, {}, store),
+        drop: async (step) => dropped(writing, step),
+    };
+    return writing;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "ultimabase",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The UltimaBase kernel and its in-memory adapter.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/ultimabase"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "bin": "./dist/cli.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./internal": "./dist/internal.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "bin": "./dist/cli.js",
+    "exports": {
+      ".": "./dist/index.js",
+      "./internal": "./dist/internal.js"
+    }
+  },
+  "dependencies": {
+    "semver": "7.8.5"
+  },
+  "devDependencies": {
+    "@ultimabase/testing": "0.1.0",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }