@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/authoring-records.js

@@ -0,0 +1,264 @@
+import { isEntity } from "./entity.js";
+import { toCamelCase } from "./names.js";
+import { propertyDefinition } from "./property.js";
+import { isIncludeList } from "./query.js";
+import { isRecord, nameToWire } from "./authoring-names.js";
+import { isMe, mePathOf, meToWire } from "./me.js";
+function targetDefinition(target) {
+    const resolved = typeof target === "function" ? target() : target;
+    return isEntity(resolved) ? resolved.definition : undefined;
+}
+/**
+ * A select property's values as stored, the option values' wire names, or as authored when
+ * `decode`. Other properties' values are data and stay as they are.
+ */
+export function selectValue(value, property, decode) {
+    const definition = propertyDefinition(property);
+    if (definition?.type !== "select") {
+        return value;
+    }
+    const convert = (child) => typeof child !== "string"
+        ? child
+        : decode
+            ? (definition.options?.find((option) => nameToWire(option.value) === child)?.value ?? child)
+            : nameToWire(child);
+    return Array.isArray(value) ? value.map(convert) : convert(value);
+}
+/** Only record keys and select identifiers convert; property values remain data. */
+export function recordFromWire(value, definition) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, child]) => {
+        const property = Object.entries(definition?.properties ?? {}).find(([key]) => nameToWire(key) === name);
+        if (property !== undefined) {
+            return [property[0], selectValue(child, property[1], true)];
+        }
+        const relationship = Object.entries(definition?.relationships ?? {}).find(([key]) => nameToWire(key) === name);
+        if (relationship !== undefined) {
+            const target = targetDefinition(relationship[1].target);
+            return [
+                relationship[0],
+                Array.isArray(child)
+                    ? child.map((item) => recordFromWire(item, target))
+                    : recordFromWire(child, target),
+            ];
+        }
+        return [toCamelCase(name), child];
+    }));
+}
+export function valuesToWire(values, definition) {
+    return Object.fromEntries(Object.entries(values).map(([name, value]) => [
+        nameToWire(name),
+        selectValue(value, definition.properties[name], false),
+    ]));
+}
+/** Translate query fields and relationships; operands of JSON filters stay opaque. */
+function whereToWire(where, definition) {
+    return Object.fromEntries(Object.entries(where).map(([name, condition]) => {
+        if ((name === "and" || name === "or") && Array.isArray(condition)) {
+            return [name, condition.map((child) => whereToWire(child, definition))];
+        }
+        if (name === "not" && isRecord(condition)) {
+            return [name, whereToWire(condition, definition)];
+        }
+        const property = definition?.properties[name];
+        const relationship = definition?.relationships?.[name];
+        if (relationship !== undefined && isRecord(condition)) {
+            const target = targetDefinition(relationship.target);
+            return [
+                nameToWire(name),
+                relationship.cardinality === "many"
+                    ? Object.fromEntries(Object.entries(condition).map(([quantifier, child]) => [
+                        quantifier,
+                        isRecord(child) ? whereToWire(child, target) : child,
+                    ]))
+                    : whereToWire(condition, target),
+            ];
+        }
+        if (isRecord(condition)) {
+            const operators = [
+                "eq",
+                "ne",
+                "in",
+                "isNull",
+                "contains",
+                "startsWith",
+                "gt",
+                "gte",
+                "lt",
+                "lte",
+                "between",
+            ];
+            if (Object.keys(condition).every((key) => operators.includes(key))) {
+                return [
+                    nameToWire(name),
+                    Object.fromEntries(Object.entries(condition).map(([key, child]) => [
+                        key,
+                        selectValue(child, property, false),
+                    ])),
+                ];
+            }
+            if (propertyDefinition(property)?.type !== "json") {
+                return [nameToWire(name), whereToWire(condition)];
+            }
+        }
+        return [nameToWire(name), selectValue(condition, property, false)];
+    }));
+}
+const FIELD_OPERATORS = [
+    "eq",
+    "ne",
+    "in",
+    "isNull",
+    "contains",
+    "startsWith",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "between",
+];
+/** The operators of a query on the wire, by their authored names. */
+const WIRE_OPERATORS = {
+    isNull: "is_null",
+    startsWith: "starts_with",
+};
+/** Whether a condition is a field filter: an object of operators, authored or wire names. */
+function isOperators(condition) {
+    const keys = Object.keys(condition);
+    return (keys.length > 0 &&
+        keys.every((key) => FIELD_OPERATORS.includes(key) || Object.values(WIRE_OPERATORS).includes(key)));
+}
+/** The declaration of `name` in a definition's record, by authored or wire name. */
+function declared(declarations, name) {
+    if (declarations === undefined) {
+        return undefined;
+    }
+    if (Object.hasOwn(declarations, name)) {
+        return declarations[name];
+    }
+    return Object.entries(declarations).find(([key]) => nameToWire(key) === name)?.[1];
+}
+/** A value of a scope on the wire: `me` and paths as `{ "$me": [...] }`, select values as stored. */
+function scopeValueToWire(value, property) {
+    const hops = mePathOf(value);
+    if (hops !== undefined) {
+        return meToWire(isMe(value) ? value : hops);
+    }
+    return selectValue(value, property, false);
+}
+function operatorsToWire(condition, property) {
+    return Object.fromEntries(Object.entries(condition).map(([key, child]) => [
+        WIRE_OPERATORS[key] ?? key,
+        scopeValueToWire(child, property),
+    ]));
+}
+/**
+ * The `where` of a scoped permission as the manifest writes it: the wire form of a query, with
+ * snake_case fields, relationships and operators, select values as stored, and `me` and paths as
+ * `{ "$me": [...] }` with snake_case hops. A relationship compared with `me`, a path or operators
+ * stays under its name. Converting a wire `where` again changes nothing.
+ */
+export function scopeWhereToWire(where, definition) {
+    if (!isRecord(where) || mePathOf(where) !== undefined) {
+        return where;
+    }
+    return Object.fromEntries(Object.entries(where).map(([name, condition]) => {
+        if ((name === "and" || name === "or") && Array.isArray(condition)) {
+            return [name, condition.map((child) => scopeWhereToWire(child, definition))];
+        }
+        if (name === "not") {
+            return [name, scopeWhereToWire(condition, definition)];
+        }
+        const property = declared(definition?.properties, name);
+        const relationship = declared(definition?.relationships, name);
+        if (mePathOf(condition) !== undefined) {
+            return [nameToWire(name), scopeValueToWire(condition, property)];
+        }
+        if (isRecord(condition) && isOperators(condition)) {
+            return [nameToWire(name), operatorsToWire(condition, property)];
+        }
+        if (relationship !== undefined && isRecord(condition)) {
+            const target = targetDefinition(relationship.target);
+            return [
+                nameToWire(name),
+                relationship.cardinality === "many"
+                    ? Object.fromEntries(Object.entries(condition).map(([quantifier, child]) => [
+                        quantifier,
+                        scopeWhereToWire(child, target),
+                    ]))
+                    : scopeWhereToWire(condition, target),
+            ];
+        }
+        if (isRecord(condition) && propertyDefinition(property)?.type !== "json") {
+            return [nameToWire(name), scopeWhereToWire(condition)];
+        }
+        return [nameToWire(name), selectValue(condition, property, false)];
+    }));
+}
+export function findToWire(options, definition) {
+    return {
+        ...options,
+        ...(options.where === undefined ? {} : { where: whereToWire(options.where, definition) }),
+        ...(options.orderBy === undefined
+            ? {}
+            : {
+                orderBy: options.orderBy.map((order) => ({ ...order, field: nameToWire(order.field) })),
+            }),
+        ...(options.include === undefined ? {} : { include: includeToWire(options.include) }),
+    };
+}
+/** A fresh metric query's metrics, grouped fields and `where` in wire names. */
+export function metricQueryToWire(options, definition) {
+    return {
+        ...options,
+        metrics: options.metrics.map(nameToWire),
+        ...(options.groupBy === undefined ? {} : { groupBy: options.groupBy.map(nameToWire) }),
+        where: whereToWire(options.where, definition),
+    };
+}
+/**
+ * A fresh metric query's row in authored names: the grouped fields as a record's, the metrics by the
+ * names the handler asked for.
+ */
+export function metricQueryRowFromWire(row, metrics, definition) {
+    const byWire = new Map(metrics.map((metric) => [nameToWire(metric), metric]));
+    const groups = Object.fromEntries(Object.entries(row).filter(([name]) => !byWire.has(name)));
+    return {
+        ...recordFromWire(groups, definition),
+        ...Object.fromEntries([...byWire].map(([wire, metric]) => [metric, row[wire] ?? null])),
+    };
+}
+/** The relationships a find includes, by wire name, in the form the handler gave them. */
+function includeToWire(include) {
+    return isIncludeList(include)
+        ? include.map(nameToWire)
+        : Object.fromEntries(Object.entries(include).map(([name, value]) => [nameToWire(name), value]));
+}
+/** Current action edits use the same property names and values as authored entity records. */
+export function editsFromWire(edits, entities) {
+    return edits.map((edit) => {
+        const definition = entities.find((entity) => nameToWire(entity.name) === edit.entity)?.definition;
+        const before = recordFromWire(Object.fromEntries(Object.entries(edit.changes).map(([field, change]) => [field, change.before])), definition);
+        const after = recordFromWire(Object.fromEntries(Object.entries(edit.changes).map(([field, change]) => [field, change.after])), definition);
+        return {
+            ...edit,
+            entity: toCamelCase(edit.entity),
+            changes: Object.fromEntries(Object.keys(before).map((field) => [
+                field,
+                { before: before[field], after: after[field] },
+            ])),
+        };
+    });
+}
+/** Generated actions return entity records; authored action results remain application data. */
+export function generatedResultFromWire(value, action, definition) {
+    if (action === "create" || action === "update") {
+        return recordFromWire(value, definition);
+    }
+    if (action.startsWith("upsert_by_") && isRecord(value)) {
+        return { ...value, record: recordFromWire(value.record, definition) };
+    }
+    return value;
+}

package/dist/authoring.d.ts

@@ -0,0 +1,15 @@
+import type { OntologyConfig } from "./analyze.js";
+import type { DiagnosticCode } from "./diagnostics.js";
+import { type AnyEntity } from "./entity.js";
+import type { Principal } from "./runtime.js";
+type Report = (code: DiagnosticCode, path: string, message: string) => void;
+export declare function principalFromWire<P extends Principal>(principal: P): P;
+/**
+ * Canonical definitions feed REST, storage and future transports; the public config stays camelCase.
+ * The built-in entities, which every ontology includes, are normalized with the declared ones.
+ */
+export declare function authoringToWire(config: OntologyConfig, builtIns: ReadonlyArray<AnyEntity>, report: Report): {
+    readonly config: OntologyConfig;
+    readonly builtIns: ReadonlyArray<AnyEntity>;
+};
+export {};

package/dist/authoring.js

@@ -0,0 +1,331 @@
+import { Schema } from "effect";
+import { isAction } from "./action.js";
+import { actionInputToWire } from "./authoring-input.js";
+import { isRecord, nameToWire, permissionToWire } from "./authoring-names.js";
+import { earlierMetricsFieldProblem, withCurrentDefinitionNames } from "./legacy.js";
+import { scopeWhereToWire, selectValue } from "./authoring-records.js";
+import { isEntity } from "./entity.js";
+import { toCamelCase } from "./names.js";
+import { inheritUnknownOptions, p, propertyDefinition, } from "./property.js";
+import { isRelationship } from "./relationship.js";
+import { isRole, member, roleEntries, rolePermissions, } from "./role.js";
+export function principalFromWire(principal) {
+    return {
+        ...principal,
+        roles: principal.roles.map(toCamelCase),
+        permissions: principal.permissions.map(toCamelCase),
+        ...(principal.scopes === undefined
+            ? {}
+            : {
+                scopes: principal.scopes.map((scope) => ({
+                    ...scope,
+                    permission: toCamelCase(scope.permission),
+                })),
+            }),
+    };
+}
+function indexToWire(index) {
+    if (Array.isArray(index)) {
+        return index.map(nameToWire);
+    }
+    const definition = index;
+    return { ...definition, properties: (definition.properties ?? []).map(nameToWire) };
+}
+/**
+ * A metric condition with wire names: its property, as `property` or, in a `filtered` expression,
+ * `column`, and the values of a select property, which are option values.
+ */
+function conditionToWire(condition, properties) {
+    if (!isRecord(condition)) {
+        return condition;
+    }
+    const key = "property" in condition ? "property" : "column";
+    const name = condition[key];
+    if (typeof name !== "string") {
+        return condition;
+    }
+    const property = isRecord(properties) && Object.hasOwn(properties, name) ? properties[name] : undefined;
+    return {
+        ...condition,
+        [key]: nameToWire(name),
+        ...("value" in condition ? { value: selectValue(condition.value, property, false) } : {}),
+        ...("values" in condition ? { values: selectValue(condition.values, property, false) } : {}),
+    };
+}
+/** A metric expression with wire names: properties, metric references and conditions. */
+function expressionToWire(value, properties) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    const expression = { ...value };
+    if (typeof value.name === "string" && (value.op === "metric" || value.op === "column")) {
+        expression.name = nameToWire(value.name);
+    }
+    if (Array.isArray(value.args)) {
+        expression.args = value.args.map((arg) => expressionToWire(arg, properties));
+    }
+    if (Array.isArray(value.where)) {
+        expression.where = value.where.map((condition) => conditionToWire(condition, properties));
+    }
+    if (typeof value.balanceOver === "string") {
+        expression.balanceOver = nameToWire(value.balanceOver);
+    }
+    return expression;
+}
+/** Preserve shared definitions and lazy relationship targets while building the canonical model. */
+class AuthoringEncoder {
+    report;
+    definitionsByName;
+    entities = new WeakMap();
+    definitions = new WeakMap();
+    properties = new WeakMap();
+    roles = new WeakMap();
+    constructor(report, 
+    /** The authored definitions of the entities, by wire name, which scopes are converted with. */
+    definitionsByName = new Map()) {
+        this.report = report;
+        this.definitionsByName = definitionsByName;
+    }
+    name(name, path) {
+        const encoded = nameToWire(name);
+        if (typeof name === "string" &&
+            /^[a-z][a-zA-Z0-9]*$/.test(name) &&
+            name !== toCamelCase(encoded)) {
+            this.report("invalid-name", path, `Use lower camelCase ${toCamelCase(encoded)} ` +
+                "so the TypeScript and wire names round-trip.");
+        }
+        return encoded;
+    }
+    named(values, path, convert) {
+        const result = Object.create(null);
+        for (const [name, value] of Object.entries(values ?? {})) {
+            const fieldPath = `${path}.${name}`;
+            const wireName = this.name(name, fieldPath);
+            if (Object.hasOwn(result, wireName)) {
+                this.report("duplicate-name", fieldPath, `Names collide on ${wireName} after snake_case conversion.`);
+            }
+            result[wireName] = convert(value, fieldPath);
+        }
+        return result;
+    }
+    property(value, path) {
+        if (!Schema.isSchema(value)) {
+            return value;
+        }
+        const cached = this.properties.get(value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let normalized = value;
+        const definition = propertyDefinition(value);
+        if (definition?.type === "select") {
+            const options = (definition.options ?? []).map((option) => ({
+                ...option,
+                description: option.description ?? "",
+                value: nameToWire(option.value),
+            }));
+            for (const option of definition.options ?? []) {
+                this.name(option.value, `${path}.options`);
+            }
+            // The definition's own fields are not options of p.select.
+            const settings = { ...definition };
+            delete settings.type;
+            delete settings.options;
+            if (typeof settings.default === "string") {
+                settings.default = nameToWire(settings.default);
+            }
+            normalized = p.select(options, settings);
+            inheritUnknownOptions(value, normalized);
+        }
+        this.properties.set(value, normalized);
+        return normalized;
+    }
+    target(value) {
+        if (typeof value === "string") {
+            return nameToWire(value);
+        }
+        if (typeof value === "function") {
+            return () => this.entity(value());
+        }
+        return this.entity(value);
+    }
+    relationship(value) {
+        if (!isRelationship(value)) {
+            return value;
+        }
+        const normalized = {
+            ...value,
+            inverse: nameToWire(value.inverse),
+            target: this.target(value.target),
+        };
+        if ("on" in value && value.on !== undefined) {
+            return {
+                ...normalized,
+                on: Object.fromEntries(Object.entries(value.on).map(([property, target]) => [
+                    nameToWire(property),
+                    nameToWire(target),
+                ])),
+            };
+        }
+        return normalized;
+    }
+    definition(entity) {
+        const declared = entity.definition;
+        const cached = this.definitions.get(declared);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const problem = earlierMetricsFieldProblem(declared);
+        if (problem !== undefined) {
+            this.report("invalid-metric", `${entity.name}.metrics`, problem);
+        }
+        const original = withCurrentDefinitionNames(declared);
+        const normalized = {
+            ...original,
+            title: nameToWire(original.title),
+            ...(original.source?.currency === undefined
+                ? {}
+                : { source: { ...original.source, currency: nameToWire(original.source.currency) } }),
+            properties: this.named(original.properties, `${entity.name}.properties`, (value, path) => this.property(value, path)),
+            relationships: this.named(original.relationships ?? {}, `${entity.name}.relationships`, (value) => this.relationship(value)),
+            ...(original.indexes === undefined ? {} : { indexes: original.indexes.map(indexToWire) }),
+            ...(original.metrics === undefined
+                ? {}
+                : {
+                    metrics: this.named(original.metrics, `${entity.name}.metrics`, (value) => expressionToWire(value, original.properties)),
+                }),
+        };
+        this.definitions.set(declared, normalized);
+        return normalized;
+    }
+    action(value, path) {
+        if (!isAction(value)) {
+            return value;
+        }
+        let input = value.input;
+        try {
+            if (Schema.isSchema(input)) {
+                input = actionInputToWire(input);
+            }
+        }
+        catch (error) {
+            this.report("invalid-action-input", `${path}.input`, error instanceof Error ? error.message : String(error));
+        }
+        const normalized = {
+            ...value,
+            input,
+            permission: value.permission === undefined ? undefined : permissionToWire(value.permission),
+        };
+        if (typeof value.handler === "function") {
+            normalized.handler = (context) => value.handler({ ...context, principal: principalFromWire(context.principal) });
+        }
+        if (typeof value.prepare === "function") {
+            const prepare = value.prepare;
+            normalized.prepare = (context) => prepare({ ...context, principal: principalFromWire(context.principal) });
+        }
+        return normalized;
+    }
+    entity(value) {
+        if (!isEntity(value)) {
+            return value;
+        }
+        const cached = this.entities.get(value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Register the handle before resolving relationships, which can point back to it.
+        const normalized = { ...value, name: this.name(value.name, value.name) };
+        this.entities.set(value, normalized);
+        const definition = this.definition(value);
+        Object.assign(normalized, {
+            definition,
+            properties: definition.properties,
+            relationships: definition.relationships,
+        });
+        if (isRecord(value.actions)) {
+            Object.assign(normalized, {
+                actions: this.named(value.actions, `${value.name}.actions`, (action, path) => this.action(action, path)),
+            });
+        }
+        return normalized;
+    }
+    role(value) {
+        if (!isRole(value) || value === member) {
+            return value;
+        }
+        const cached = this.roles.get(value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const rebuilt = Array.isArray(value.permissions)
+            ? rolePermissions(roleEntries(value.permissions, value.scopes ?? []).map((entry) => this.permission(entry)))
+            : { permissions: value.permissions, scopes: value.scopes ?? [] };
+        // The scoped entries `role()` dropped, and those only wire names make duplicates, for `check`.
+        const { unusedScopes: dropped = [], ...rest } = value;
+        const unusedScopes = [
+            ...dropped.map((scope) => this.permission(scope)),
+            ...(rebuilt.unusedScopes ?? []),
+        ];
+        const normalized = {
+            ...rest,
+            name: this.name(value.name, `roles.${value.name}`),
+            permissions: rebuilt.permissions,
+            scopes: rebuilt.scopes,
+            ...(unusedScopes.length === 0 ? {} : { unusedScopes }),
+        };
+        this.roles.set(value, normalized);
+        return normalized;
+    }
+    /** A role or member permission with wire names: its permission and, when scoped, its `where`. */
+    permission(value) {
+        return typeof value === "string" || !isRecord(value)
+            ? permissionToWire(value)
+            : this.scope(value);
+    }
+    scope(value) {
+        if (!isRecord(value) || typeof value.permission !== "string") {
+            return value;
+        }
+        const permission = permissionToWire(value.permission);
+        const definition = this.definitionsByName.get(permission.split(":")[0] ?? "");
+        return {
+            ...value,
+            permission,
+            where: scopeWhereToWire(value.where, definition),
+        };
+    }
+}
+/**
+ * Canonical definitions feed REST, storage and future transports; the public config stays camelCase.
+ * The built-in entities, which every ontology includes, are normalized with the declared ones.
+ */
+export function authoringToWire(config, builtIns, report) {
+    const definitionsByName = new Map();
+    for (const candidate of [...builtIns, ...(config.entities ?? [])]) {
+        if (isEntity(candidate) && typeof candidate.name === "string") {
+            definitionsByName.set(nameToWire(candidate.name), candidate.definition);
+        }
+    }
+    const encoder = new AuthoringEncoder(report, definitionsByName);
+    const problem = earlierMetricsFieldProblem(config);
+    if (problem !== undefined) {
+        report("invalid-metric", "metrics", problem);
+    }
+    const normalized = {
+        ...withCurrentDefinitionNames(config),
+        entities: (config.entities ?? []).map((entity) => encoder.entity(entity)),
+        ...(config.roles === undefined
+            ? {}
+            : { roles: config.roles.map((role) => encoder.role(role)) }),
+    };
+    if (isRecord(config.signIn) && typeof config.signIn.onNewUser === "string") {
+        normalized.signIn = { ...config.signIn, onNewUser: permissionToWire(config.signIn.onNewUser) };
+    }
+    if (isRecord(config.member) && Array.isArray(config.member.permissions)) {
+        normalized.member = {
+            ...config.member,
+            permissions: config.member.permissions.map((permission) => encoder.permission(permission)),
+        };
+    }
+    return { config: normalized, builtIns: builtIns.map((entity) => encoder.entity(entity)) };
+}

package/dist/bin/check.d.ts

@@ -0,0 +1,30 @@
+import { type OntologyManifest } from "../manifest.js";
+import type { LoadResult, OntologyLoader } from "./load.js";
+import { type ExitCode, type Output } from "./output.js";
+/** What `check` prints on success: a summary, the manifest JSON or the catalog as prose. */
+export type CheckFormat = "summary" | "manifest" | "catalog";
+export interface CheckInput {
+    readonly entry: string;
+    readonly format: CheckFormat;
+}
+export interface CheckDependencies {
+    readonly load: OntologyLoader;
+    readonly output: Output;
+}
+type Loaded = Extract<LoadResult, {
+    readonly _tag: "Loaded";
+}>;
+/** Counts and names of what the manifest declares, the built-in `User` and `member` included. */
+export declare function catalogSummary(manifest: OntologyManifest): string;
+/**
+ * Loads the ontology and reports every diagnostic on stderr. Returns the loaded ontology, or
+ * undefined when it does not load or has errors.
+ */
+export declare function loadCheckedOntology(entry: string, dependencies: CheckDependencies): Promise<Loaded | undefined>;
+/**
+ * `segmentstream-ontology check`: loads the ontology as the deploy pipeline does, reports what
+ * `check` found and prints the catalog summary, the manifest or the catalog prose. Diagnostics go to
+ * stderr; any error fails the command.
+ */
+export declare function checkCommand(input: CheckInput, dependencies: CheckDependencies): Promise<ExitCode>;
+export {};