@sincpro/mobile 0.4.4 → 1.0.0

package/dist/domain/database/criteria_sql.js

@@ -0,0 +1,476 @@
+import { InvalidCriteria, isOperator, } from "@sincpro/criteria";
+import { criteriaOf } from "./criteria";
+import { deviceClock, periodBounds, readCriteriaValue, } from "./criteria_clock";
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_DEPTH = 8;
+export { deviceClock };
+export function compileCriteria(asked, target, clock = deviceClock()) {
+    assertName(target.table, "table");
+    if (!(clock.now instanceof Date) || Number.isNaN(clock.now.getTime())) {
+        throw new InvalidCriteria("the criteria clock has no instant");
+    }
+    const criteria = criteriaOf(asked);
+    if (criteria.grouping !== undefined) {
+        throw new InvalidCriteria("a document query answers a selection, not a grouping");
+    }
+    const params = [];
+    const compiled = criteria.selection
+        ? compileExpression(criteria.selection, target, params, 0, clock)
+        : { sql: "", predicate: { op: "true" } };
+    const order = (criteria.order ?? []).map((sort) => ({
+        ref: fieldRef(sort.field, target),
+        descending: sort.descending === true,
+    }));
+    const page = pageOf(criteria.pagination);
+    if ((page.limit !== undefined || page.offset > 0) &&
+        !order.some((item) => item.ref.name === "uuid")) {
+        order.push({
+            ref: fieldRef("uuid", { ...target, column: () => true }),
+            descending: false,
+        });
+    }
+    return {
+        whereSql: compiled.sql,
+        params,
+        orderSql: order
+            .map((item) => `${sqlOf(target.table, item.ref)} ${item.descending ? "DESC" : "ASC"}`)
+            .join(", "),
+        order,
+        limit: page.limit,
+        offset: page.offset,
+        predicate: compiled.predicate,
+    };
+}
+export function rowsFor(compiled, rows, others = () => []) {
+    const matched = rows.filter((row) => holds(row, compiled.predicate, others));
+    const ordered = compiled.order.length === 0
+        ? [...matched]
+        : [...matched].sort((left, right) => compareRows(left, right, compiled.order));
+    const start = compiled.offset;
+    const end = compiled.limit === undefined ? undefined : start + compiled.limit;
+    return ordered.slice(start, end);
+}
+function compileExpression(expression, target, params, depth, clock) {
+    if ("through" in expression && "selection" in expression) {
+        return compileThrough(expression, target, params, depth, clock);
+    }
+    if ("all" in expression)
+        return compileGroup("and", "AND", expression.all, target, params, depth, clock);
+    if ("any" in expression)
+        return compileGroup("or", "OR", expression.any, target, params, depth, clock);
+    if ("negate" in expression) {
+        const inner = compileExpression(expression.negate, target, params, depth, clock);
+        return {
+            sql: `NOT ((${inner.sql || "1"}) IS TRUE)`,
+            predicate: { op: "not", item: inner.predicate },
+        };
+    }
+    if (!("field" in expression) || !isOperator(expression.operator)) {
+        throw new InvalidCriteria("a criteria condition needs a field and an operator");
+    }
+    return compileCondition(expression.field, expression.operator, expression.value, target, params, clock);
+}
+function compileGroup(op, sqlOp, parts, target, params, depth, clock) {
+    if (parts.length === 0) {
+        const open = op === "and";
+        return { sql: open ? "(1)" : "(0)", predicate: { op: open ? "true" : "false" } };
+    }
+    const compiled = parts.map((part) => compileExpression(part, target, params, depth, clock));
+    return {
+        sql: `(${compiled.map((part) => part.sql).join(` ${sqlOp} `)})`,
+        predicate: { op, items: compiled.map((part) => part.predicate) },
+    };
+}
+function compileThrough(expression, parent, params, depth, clock) {
+    if (depth >= MAX_DEPTH) {
+        throw new InvalidCriteria("a criteria crosses too many relations");
+    }
+    assertName(expression.through, "relation");
+    const child = parent.relation?.(expression.through);
+    if (!child)
+        throw new InvalidCriteria(`unknown relation '${expression.through}'`);
+    assertName(child.table, "table");
+    const inner = compileExpression(expression.selection, child, params, depth + 1, clock);
+    const link = `json_extract(${parent.table}.data, '$.${expression.through}')`;
+    const each = `json_each(${parent.table}.data, '$.${expression.through}')`;
+    return {
+        sql: `EXISTS (SELECT 1 FROM ${child.table} WHERE (` +
+            `${child.table}.uuid = ${link} OR ${child.table}.uuid IN (SELECT value FROM ${each}))` +
+            ` AND (${inner.sql || "1"}))`,
+        predicate: {
+            op: "exists",
+            table: child.table,
+            link: expression.through,
+            item: inner.predicate,
+        },
+    };
+}
+function compileCondition(field, operator, value, target, params, clock) {
+    const left = fieldRef(field, target);
+    const expr = sqlOf(target.table, left);
+    if (isFieldValue(value)) {
+        const right = fieldRef(value.name, target);
+        return {
+            sql: compare(expr, operator, sqlOf(target.table, right), params, undefined, true),
+            predicate: { op: "cmp", left, operator, right: { field: right } },
+        };
+    }
+    if (isPeriodValue(value)) {
+        if (operator !== "between") {
+            throw new InvalidCriteria(`a period is a range and takes the operator 'between'; '${field}' asked it with '${operator}'`);
+        }
+        const [start, end] = periodBounds(value, clock);
+        const lower = compileCondition(field, ">=", start, target, params, clock);
+        const upper = compileCondition(field, "<", end, target, params, clock);
+        return {
+            sql: `(${lower.sql} AND ${upper.sql})`,
+            predicate: { op: "and", items: [lower.predicate, upper.predicate] },
+        };
+    }
+    const bound = literal(operator, readCriteriaValue(value, clock, field));
+    return {
+        sql: compare(expr, operator, "?", params, bound, false),
+        predicate: { op: "cmp", left, operator, right: { value: bound } },
+    };
+}
+function compare(left, operator, rightSql, params, bound, againstField) {
+    if (againstField) {
+        switch (operator) {
+            case "=":
+            case "!=":
+            case ">":
+            case ">=":
+            case "<":
+            case "<=":
+                return `${left} ${operator} ${rightSql}`;
+            default:
+                throw new InvalidCriteria(`'${operator}' compares against a value`);
+        }
+    }
+    if (operator === "=" && Array.isArray(bound) && bound.length === 0) {
+        return `(${left} IS NULL OR CAST(${left} AS TEXT) = '[]')`;
+    }
+    if (operator === "!=" && Array.isArray(bound) && bound.length === 0) {
+        return `(${left} IS NOT NULL AND CAST(${left} AS TEXT) != '[]')`;
+    }
+    if ((operator === "=" || operator === "!=") && bound === null) {
+        return operator === "=" ? `${left} IS NULL` : `${left} IS NOT NULL`;
+    }
+    switch (operator) {
+        case "=":
+        case "!=":
+        case ">":
+        case ">=":
+        case "<":
+        case "<=":
+            push(params, bound);
+            return `${left} ${operator} ${rightSql}`;
+        case "between": {
+            const pair = pairOf(bound);
+            params.push(pair[0], pair[1]);
+            return `${left} BETWEEN ? AND ?`;
+        }
+        case "in":
+        case "not in":
+            return membership(left, operator === "not in", listOf(bound), params);
+        case "is null":
+            if (bound !== 0 && bound !== 1) {
+                throw new InvalidCriteria("'is null' compares against true or false");
+            }
+            return bound === 0 ? `${left} IS NOT NULL` : `${left} IS NULL`;
+        case "like":
+            params.push(`%${escaped(text(bound).toLowerCase())}%`);
+            return `lower(${left}) LIKE ? ESCAPE '\\'`;
+        case "starts with":
+            params.push(`${escaped(text(bound).toLowerCase())}%`);
+            return `lower(${left}) LIKE ? ESCAPE '\\'`;
+        case "contains":
+            params.push(`%"${escaped(text(bound))}"%`);
+            return `CAST(${left} AS TEXT) LIKE ? ESCAPE '\\'`;
+        case "not contains":
+            params.push(`%"${escaped(text(bound))}"%`);
+            return `NOT ((CAST(${left} AS TEXT) LIKE ? ESCAPE '\\') IS TRUE)`;
+        default:
+            throw new InvalidCriteria(`no SQL translation for operator '${operator}'`);
+    }
+}
+function membership(left, negated, values, params) {
+    if (values.length === 0)
+        return negated ? "(1)" : "(0)";
+    params.push(...values);
+    const marks = values.map(() => "?").join(", ");
+    return `${left} ${negated ? "NOT IN" : "IN"} (${marks})`;
+}
+function pageOf(pagination) {
+    if (!pagination)
+        return { offset: 0 };
+    if (pagination.strategy && "token" in pagination.strategy) {
+        throw new InvalidCriteria("a document query pages by rows, not by a token");
+    }
+    const offset = pagination.strategy && "rows" in pagination.strategy ? pagination.strategy.rows : 0;
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new InvalidCriteria("a page offset is a whole number from zero");
+    }
+    if (pagination.limit === undefined)
+        return { offset };
+    if (!Number.isInteger(pagination.limit) || pagination.limit < 0) {
+        throw new InvalidCriteria("a page limit is a whole number from zero");
+    }
+    return { limit: pagination.limit, offset };
+}
+function fieldRef(field, target) {
+    const segments = field.split(".");
+    if (segments.length === 0 || segments.some((segment) => !IDENTIFIER.test(segment))) {
+        throw new InvalidCriteria(`invalid field '${field}'`);
+    }
+    if (target.column(field)) {
+        if (segments.length !== 1)
+            throw new InvalidCriteria(`'${field}' is not a column`);
+        return { kind: "column", name: field, path: "" };
+    }
+    return { kind: "json", name: field, path: `$.${segments.join(".")}` };
+}
+function sqlOf(table, ref) {
+    if (ref.kind === "column")
+        return `${table}.${ref.name}`;
+    return `json_extract(${table}.data, '${ref.path}')`;
+}
+function literal(operator, value) {
+    if (operator === "in" || operator === "not in" || operator === "between") {
+        if (!Array.isArray(value))
+            throw new InvalidCriteria(`'${operator}' compares against a list`);
+        return value.map((item) => {
+            if (isDynamic(item) || Array.isArray(item)) {
+                throw new InvalidCriteria(`'${operator}' compares against text, numbers, or null`);
+            }
+            return scalarParam(item);
+        });
+    }
+    if (operator === "=" && Array.isArray(value) && value.length === 0)
+        return [];
+    if (operator === "!=" && Array.isArray(value) && value.length === 0)
+        return [];
+    if (Array.isArray(value) || isDynamic(value)) {
+        throw new InvalidCriteria(`'${operator}' compares against one value`);
+    }
+    if (operator === "is null") {
+        if (typeof value !== "boolean") {
+            throw new InvalidCriteria("'is null' compares against true or false");
+        }
+        return value ? 1 : 0;
+    }
+    return scalarParam(value);
+}
+function scalarParam(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (value === null || typeof value === "number" || typeof value === "string")
+        return value;
+    throw new InvalidCriteria("a criteria value must be text, a number, or null");
+}
+function pairOf(bound) {
+    if (!Array.isArray(bound) || bound.length !== 2) {
+        throw new InvalidCriteria("'between' compares against two values");
+    }
+    return [bound[0], bound[1]];
+}
+function listOf(bound) {
+    if (!Array.isArray(bound))
+        throw new InvalidCriteria("'in' compares against a list");
+    return bound;
+}
+function push(params, bound) {
+    if (bound === undefined || Array.isArray(bound)) {
+        throw new InvalidCriteria("a comparison needs one value");
+    }
+    params.push(bound);
+}
+function text(bound) {
+    if (typeof bound === "string" || typeof bound === "number")
+        return String(bound);
+    throw new InvalidCriteria("a text comparison needs text or a number");
+}
+function escaped(value) {
+    return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+function isDynamic(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof Date) &&
+        "$" in value);
+}
+function isPeriodValue(value) {
+    return isDynamic(value) && value.$ === "period";
+}
+function isFieldValue(value) {
+    return isDynamic(value) && value.$ === "field";
+}
+function assertName(name, label) {
+    if (!IDENTIFIER.test(name))
+        throw new InvalidCriteria(`invalid ${label} '${name}'`);
+}
+function holds(row, predicate, others) {
+    switch (predicate.op) {
+        case "true":
+            return true;
+        case "false":
+            return false;
+        case "not":
+            return !holds(row, predicate.item, others);
+        case "and":
+            return predicate.items.every((item) => holds(row, item, others));
+        case "or":
+            return predicate.items.some((item) => holds(row, item, others));
+        case "exists": {
+            const ids = linkedIds(row, predicate.link);
+            if (ids.length === 0)
+                return false;
+            return others(predicate.table).some((child) => ids.includes(child.uuid) && holds(child, predicate.item, others));
+        }
+        case "cmp":
+            return compareValues(readField(row, predicate.left), predicate.operator, "field" in predicate.right
+                ? readField(row, predicate.right.field)
+                : predicate.right.value);
+    }
+}
+function linkedIds(row, field) {
+    const value = readJson(row.data, `$.${field}`);
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === "string");
+    return [];
+}
+function readField(row, ref) {
+    if (ref.kind === "column") {
+        if (ref.name === "uuid")
+            return row.uuid;
+        if (ref.name === "version")
+            return row.version;
+        return row.columns[ref.name] ?? null;
+    }
+    return readJson(row.data, ref.path);
+}
+function readJson(data, path) {
+    const segments = path.startsWith("$.") ? path.slice(2).split(".") : [];
+    let current = JSON.parse(data);
+    for (const segment of segments) {
+        if (current === null || typeof current !== "object")
+            return null;
+        current = current[segment];
+    }
+    return current === undefined ? null : current;
+}
+function compareValues(left, operator, right) {
+    if (operator === "=" && Array.isArray(right) && right.length === 0) {
+        return left == null || (Array.isArray(left) && left.length === 0);
+    }
+    if (operator === "!=" && Array.isArray(right) && right.length === 0) {
+        return left != null && !(Array.isArray(left) && left.length === 0);
+    }
+    if (operator === "=" && right === null)
+        return left == null;
+    if (operator === "!=" && right === null)
+        return left != null;
+    switch (operator) {
+        case "=":
+            return same(left, right);
+        case "!=":
+            return !same(left, right);
+        case ">":
+        case ">=":
+        case "<":
+        case "<=":
+            return ordered(left, right, operator);
+        case "between": {
+            if (!Array.isArray(right) || right.length !== 2)
+                return false;
+            return ordered(left, right[0], ">=") && ordered(left, right[1], "<=");
+        }
+        case "in":
+            return Array.isArray(right) && right.some((item) => same(left, item));
+        case "not in":
+            return Array.isArray(right) && !right.some((item) => same(left, item));
+        case "is null":
+            return right === 0 || right === false ? left != null : left == null;
+        case "like":
+            return (left != null &&
+                String(scalar(left)).toLowerCase().includes(String(right).toLowerCase()));
+        case "starts with":
+            return (left != null &&
+                String(scalar(left)).toLowerCase().startsWith(String(right).toLowerCase()));
+        case "contains":
+            return quoted(left, String(right));
+        case "not contains":
+            return left == null || !quoted(left, String(right));
+        default:
+            return false;
+    }
+}
+function quoted(value, needle) {
+    const mark = `"${needle}"`;
+    if (typeof value === "string")
+        return value.includes(mark);
+    if (value == null)
+        return false;
+    return JSON.stringify(value).includes(mark);
+}
+function same(left, right) {
+    return scalar(left) === scalar(right);
+}
+function ordered(left, right, operator) {
+    if (scalar(left) === null || scalar(right) === null)
+        return false;
+    const compared = compareUnknown(left, right);
+    if (operator === "<")
+        return compared < 0;
+    if (operator === "<=")
+        return compared <= 0;
+    if (operator === ">")
+        return compared > 0;
+    return compared >= 0;
+}
+function compareRows(left, right, order) {
+    for (const item of order) {
+        const compared = compareUnknown(readField(left, item.ref), readField(right, item.ref));
+        if (compared === 0)
+            continue;
+        return item.descending ? -compared : compared;
+    }
+    return 0;
+}
+function compareUnknown(left, right) {
+    const a = scalar(left);
+    const b = scalar(right);
+    if (a === null && b === null)
+        return 0;
+    if (a === null)
+        return -1;
+    if (b === null)
+        return 1;
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    const as = String(a);
+    const bs = String(b);
+    if (as < bs)
+        return -1;
+    if (as > bs)
+        return 1;
+    return 0;
+}
+function scalar(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "number")
+        return Number.isNaN(value) ? null : value;
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    return null;
+}

package/dist/domain/database/database.d.ts

@@ -13,4 +13,5 @@ export interface ITable {
 export interface IMigration {
     name: string;
     migrationFn: () => Promise<void>;
+    tables?: readonly string[];
 }

package/dist/domain/database/index.d.ts

@@ -1,2 +1,4 @@
+export * from "../../domain/database/criteria";
+export * from "../../domain/database/criteria_sql";
 export * from "../../domain/database/database";
-export * from "../../domain/database/repository";
+export * from "../../domain/database/migration_plan";

package/dist/domain/database/index.js

@@ -1,2 +1,4 @@
+export * from "../../domain/database/criteria";
+export * from "../../domain/database/criteria_sql";
 export * from "../../domain/database/database";
-export * from "../../domain/database/repository";
+export * from "../../domain/database/migration_plan";

package/dist/domain/database/migration_plan.d.ts

@@ -0,0 +1,14 @@
+import { type IMigration } from "./database";
+export interface ColumnDefinition {
+    name: string;
+    definition: string;
+}
+export declare function migrationTables(migration: IMigration): string[];
+export declare function migrationsNewerThanApp(applied: Iterable<string>, known: readonly string[]): string[];
+export declare function applyMigrationStep(migration: IMigration, transaction: (work: () => Promise<void>) => Promise<void>, mark: (name: string) => Promise<void>): Promise<void>;
+export declare function pendingMigrations(migrations: readonly IMigration[], applied: ReadonlySet<string>): IMigration[];
+export declare function resetPlan(migrations: readonly IMigration[], persisted: readonly string[]): {
+    drop: string[];
+    forget: string[];
+};
+export declare function missingColumns(existing: readonly string[], wanted: readonly ColumnDefinition[]): ColumnDefinition[];

package/dist/domain/database/migration_plan.js

@@ -0,0 +1,44 @@
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function migrationTables(migration) {
+    const declared = migration.tables ?? [migration.name];
+    return declared.filter((name) => IDENTIFIER.test(name));
+}
+export function migrationsNewerThanApp(applied, known) {
+    const names = new Set(known);
+    return [...applied].filter((name) => !names.has(name)).sort();
+}
+export async function applyMigrationStep(migration, transaction, mark) {
+    await transaction(async () => {
+        await migration.migrationFn();
+        await mark(migration.name);
+    });
+}
+export function pendingMigrations(migrations, applied) {
+    const seen = new Set(applied);
+    const pending = [];
+    for (const migration of migrations) {
+        if (seen.has(migration.name))
+            continue;
+        seen.add(migration.name);
+        pending.push(migration);
+    }
+    return pending;
+}
+export function resetPlan(migrations, persisted) {
+    const keep = new Set(persisted);
+    const drop = new Set();
+    const forget = [];
+    for (const migration of migrations) {
+        const tables = migrationTables(migration);
+        const removed = tables.filter((table) => !keep.has(table));
+        for (const table of removed)
+            drop.add(table);
+        if (tables.length > 0 && removed.length === tables.length)
+            forget.push(migration.name);
+    }
+    return { drop: [...drop], forget };
+}
+export function missingColumns(existing, wanted) {
+    const have = new Set(existing);
+    return wanted.filter((column) => !have.has(column.name));
+}

package/dist/domain/entity/change_tracking.d.ts

@@ -0,0 +1,21 @@
+import { type Entity } from "../../domain/entity/entity";
+import { DomainEvent } from "../../domain/events/domain_event";
+import { type AnyClass } from "./relations";
+export declare class EntityUpdated extends DomainEvent {
+    readonly name = "entity.updated";
+    readonly label = "Updated";
+    changes: Record<string, {
+        from: string;
+        to: string;
+    }>;
+}
+export declare function fieldSnapshot(entity: Entity, seen?: Set<object>): Record<string, string>;
+type Tracked = {
+    takeSnapshot(): void;
+    recordChanges(): void;
+};
+export declare function withChangeTracking<T extends Entity, C extends AnyClass<T>>(Base: C): C & {
+    new (...args: any[]): T & Tracked;
+};
+export declare function isChangeTracked(entity: Entity): entity is Entity & Tracked;
+export {};

package/dist/domain/entity/change_tracking.js

@@ -0,0 +1,71 @@
+import { DomainEvent } from "../../domain/events/domain_event";
+import { heldEntities } from "./relations";
+const SKIPPED = new Set(["uuid", "version", "createdAt", "updatedAt", "eventIds"]);
+export class EntityUpdated extends DomainEvent {
+    name = "entity.updated";
+    label = "Updated";
+    changes = {};
+}
+export function fieldSnapshot(entity, seen = new Set()) {
+    seen.add(entity);
+    const snapshot = {};
+    for (const key of Object.keys(entity)) {
+        if (key.startsWith("_") || SKIPPED.has(key))
+            continue;
+        const value = entity[key];
+        if (typeof value === "function")
+            continue;
+        snapshot[key] = printed(value, seen);
+    }
+    return snapshot;
+}
+function printed(value, seen) {
+    const held = heldEntities(value);
+    if (held.length > 0) {
+        return JSON.stringify(held.map((one) => seen.has(one) ? { uuid: one.uuid } : fieldSnapshot(one, seen)));
+    }
+    if (Array.isArray(value))
+        return value.length === 0 ? "" : JSON.stringify(value);
+    if (value === undefined)
+        return "";
+    return JSON.stringify(value);
+}
+export function withChangeTracking(Base) {
+    class ChangeTracked extends Base {
+        _changeSnapshot = {};
+        _snapshotTaken = false;
+        // TS2545: a mixin class must declare a rest constructor.
+        // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+        constructor(...args) {
+            super(...args);
+        }
+        takeSnapshot() {
+            this._changeSnapshot = fieldSnapshot(this);
+            this._snapshotTaken = true;
+        }
+        recordChanges() {
+            if (!this._snapshotTaken)
+                return;
+            const next = fieldSnapshot(this);
+            const changes = {};
+            for (const key of new Set([
+                ...Object.keys(this._changeSnapshot),
+                ...Object.keys(next),
+            ])) {
+                if (this._changeSnapshot[key] !== next[key]) {
+                    changes[key] = {
+                        from: this._changeSnapshot[key] ?? "",
+                        to: next[key] ?? "",
+                    };
+                }
+            }
+            if (Object.keys(changes).length === 0)
+                return;
+            this.record(EntityUpdated, { changes });
+        }
+    }
+    return ChangeTracked;
+}
+export function isChangeTracked(entity) {
+    return typeof entity.recordChanges === "function";
+}

package/dist/domain/entity/checks.d.ts

@@ -0,0 +1,8 @@
+export declare function check(watches: (entity: object) => unknown): (_target: object, _key: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export interface CheckFailure {
+    rule: string;
+    message: string;
+    path: string[];
+}
+export declare function checkWarnings(entity: object, touched: readonly string[]): CheckFailure[];
+export declare function assertChecks(entity: object): void;