@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/metric.js

@@ -0,0 +1,132 @@
+/** The aggregates a metric expression may contain, `count` included. */
+export const METRIC_AGGREGATES = ["count", "sum", "countDistinct", "avg", "min", "max"];
+function binary(op) {
+    return (left, right, options) => ({ op, args: [left, right], ...options });
+}
+function reference(name, options) {
+    return { op: "metric", name, ...options };
+}
+/** An aggregate of one property of the entity. */
+function aggregate(op) {
+    return (property, options) => ({
+        op,
+        args: [{ op: "column", name: property }],
+        ...options,
+    });
+}
+/**
+ * Arithmetic combines aggregates; references name another metric of the same entity. Every
+ * aggregate takes `where`, conditions on properties of the entity that the rows it reads must meet,
+ * and `balanceOver`, the date its rows are snapshots over. In `defineOntology({ metrics })`,
+ * references name metrics of entities, `m.ref("sales.revenue")`, or other model metrics, and
+ * arithmetic and references take `align`.
+ */
+export const m = {
+    count: (options) => ({ op: "count", ...options }),
+    /** The sum of an integer or number property. */
+    sum: aggregate("sum"),
+    /**
+     * The number of distinct non-null values of a text, email, url, select, integer, date or timestamp
+     * property. Distinct counts do not add up across groups.
+     */
+    countDistinct: aggregate("countDistinct"),
+    /** The average of an integer or number property, ignoring nulls. Averages do not add up. */
+    avg: aggregate("avg"),
+    /** The least value of an integer or number property. Minimums do not add up. */
+    min: aggregate("min"),
+    /** The greatest value of an integer or number property. Maximums do not add up. */
+    max: aggregate("max"),
+    ref: reference,
+    literal: (value, options) => ({
+        op: "literal",
+        value: String(value),
+        ...options,
+    }),
+    add: binary("add"),
+    subtract: binary("subtract"),
+    multiply: binary("multiply"),
+    divide: binary("divide"),
+};
+/** The conditions an expression declares: an aggregate's `where` option, or a `filtered` node's. */
+export function conditionsOf(value) {
+    return "where" in value ? value.where : undefined;
+}
+/** The balance property an expression node declares: an aggregate's `balanceOver` option. */
+export function balanceOf(value) {
+    return "balanceOver" in value ? value.balanceOver : undefined;
+}
+/**
+ * The balance properties a metric's own aggregates declare, top-level or inside arithmetic and
+ * `filtered` expressions, without duplicates. References are not followed: the platform inherits a
+ * referenced metric's balance itself.
+ */
+export function balancesOf(value) {
+    const balances = new Set();
+    const visit = (expression, depth) => {
+        const balance = balanceOf(expression);
+        if (typeof balance === "string") {
+            balances.add(balance);
+        }
+        if ("args" in expression && Array.isArray(expression.args) && depth < 30) {
+            for (const arg of expression.args) {
+                visit(arg, depth + 1);
+            }
+        }
+    };
+    visit(value, 0);
+    return [...balances];
+}
+/** The property a condition names: `property` as authored, `column` in a `filtered` expression. */
+export function conditionProperty(condition) {
+    if ("property" in condition) {
+        return condition.property;
+    }
+    return "column" in condition ? condition.column : undefined;
+}
+function columnCondition(condition, columns) {
+    const property = "property" in condition ? condition.property : condition.column;
+    return {
+        column: columns.get(property) ?? property,
+        operator: condition.operator,
+        ...(condition.value === undefined ? {} : { value: condition.value }),
+        ...(condition.values === undefined ? {} : { values: [...condition.values] }),
+    };
+}
+function bareExpression(value, columns) {
+    switch (value.op) {
+        case "count":
+            return { op: "count" };
+        case "column":
+            return { op: "column", name: columns.get(value.name) ?? value.name };
+        case "metric":
+            return { op: "metric", name: value.name };
+        case "literal":
+            return { op: "literal", value: value.value };
+        case "filtered":
+            return {
+                op: "filtered",
+                args: value.args.map((arg) => metricExpression(arg, columns)),
+                where: value.where.map((condition) => columnCondition(condition, columns)),
+            };
+        default:
+            return { op: value.op, args: value.args.map((arg) => metricExpression(arg, columns)) };
+    }
+}
+/**
+ * Strip authoring options and resolve logical properties to physical columns for the manifest: a
+ * warehouse-backed property's `column`, or a stored property's replication view column, which is its
+ * wire name. An aggregate's `where` becomes the `filtered` expression that wraps it, its conditions
+ * naming columns too.
+ */
+export function metricExpression(value, columns) {
+    const expression = bareExpression(value, columns);
+    const where = conditionsOf(value);
+    if (where === undefined || value.op === "filtered") {
+        return expression;
+    }
+    return {
+        op: "filtered",
+        args: [expression],
+        where: where.map((condition) => columnCondition(condition, columns)),
+    };
+}

package/dist/migrate/apply.d.ts

@@ -0,0 +1,94 @@
+import { Duration, Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { type OntologyManifest } from "../manifest.js";
+import { CatalogInvalid, CatalogMismatch, MigrationFailed, MigrationRefused } from "./errors.js";
+import { RetainedStorage, type MigrationPlan } from "./model.js";
+import { type MigrationOptions, type StorageNames } from "./plan.js";
+export interface CatalogInput {
+    /** An Effect SQL client on the workspace's ontology database. */
+    readonly sql: SqlClient.SqlClient;
+}
+export interface ApplyMigrationOptions extends CatalogInput {
+    /**
+     * Connected as the schema owner (`ontology_owner`) over a direct connection, and not inside a
+     * transaction: non-transactional steps such as `CREATE INDEX CONCURRENTLY` run on their own.
+     */
+    readonly sql: SqlClient.SqlClient;
+    /** `statement_timeout` inside the migration transaction. Defaults to 5 minutes. */
+    readonly statementTimeout?: Duration.Input;
+    /**
+     * `lock_timeout` inside the migration transaction, so that DDL never holds up app traffic queued
+     * behind it for long. Defaults to 5 seconds.
+     */
+    readonly lockTimeout?: Duration.Input;
+    /**
+     * The workspace the database belongs to. With it, the migration creates, reactivates and
+     * deactivates the workflow users (`workflows:<workspace id>:<workflow name>`) so they match the
+     * target's workflows, in the transaction that records the target. Deploy passes it; without it,
+     * workflow users are left as they are and created by their first run.
+     */
+    readonly workspaceId?: string;
+}
+export interface MigrationResult {
+    /** The hash the catalog records once the migration is applied. */
+    readonly hash: string;
+    readonly appliedSteps: number;
+    /** False when the plan was a no-op and nothing was written. */
+    readonly changed: boolean;
+}
+export interface MigrateInput extends ApplyMigrationOptions {
+    readonly target: OntologyManifest;
+    readonly options?: MigrationOptions;
+}
+export type ApplyMigrationError = MigrationRefused | CatalogMismatch | CatalogInvalid | MigrationFailed | SqlError;
+/**
+ * The manifest recorded by the last applied migration, or undefined when none was applied. It is
+ * decoded with the manifest contract, so fields this SDK does not know are dropped.
+ */
+export declare const readCatalog: (input: CatalogInput) => Effect.Effect<OntologyManifest | undefined, CatalogInvalid | SqlError>;
+/**
+ * The storage the catalog records as kept: what removals retained, which declaring the entity or
+ * @legacy ontology.pre-upgrade-database-tolerance
+ * field again restores. An earlier SDK's catalog records none, and its `_ontology` table has no
+ * `retained` column; older SDKs neither read nor write it.
+ */
+export declare const readRetainedStorage: (input: CatalogInput) => Effect.Effect<RetainedStorage, CatalogInvalid | SqlError>;
+/**
+ * The names in the current schema, for `planMigration`'s `existingStorage`: relations and types,
+ * which share one namespace, and the columns of each table. Names starting with `_`, which no
+ * entity's storage uses, are left out.
+ */
+export declare const readStorageNames: (input: CatalogInput) => Effect.Effect<StorageNames, SqlError>;
+/**
+ * Applies a plan. Non-transactional steps run first, each statement on its own; they only add enum
+ * values and build indexes concurrently, and are safe to run again after a failure. Every other step
+ * then runs in one transaction with `statement_timeout` and `lock_timeout` set, which also verifies
+ * that the catalog still records the manifest the plan starts from and finally records the target. A
+ * failure rolls the transaction back and leaves the applied version in place. With `workspaceId`,
+ * the same transaction then reconciles the workflow users with the target's workflows. A no-op plan
+ * writes nothing else when the runtime schema is also current; with `workspaceId` it still
+ * reconciles the workflow users, under the migration lock while the catalog records its target.
+ */
+export declare const applyMigration: (plan: MigrationPlan, options: ApplyMigrationOptions) => Effect.Effect<MigrationResult, ApplyMigrationError>;
+/**
+ * Reads the catalog, plans the migration to the target and applies it. Run it on a Neon branch of the
+ * workspace database first as a dry run, then on production: the plan is made against each database's
+ * own catalog.
+ */
+/** The runtime's tables, beside the catalog and the entity tables. */
+export declare const RUNTIME_TABLES: ReadonlyArray<string>;
+/**
+ * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an
+ * earlier SDK migrated lacks the tables added since.
+ * A grants table without app-session binding is reported incomplete so the idempotent OAuth DDL
+ * also upgrades an unchanged manifest, and so is an attachments table whose source check predates
+ * one of {@link ATTACHMENT_SOURCES}, which the idempotent attachment DDL widens.
+ */
+export declare const readRuntimeTables: (input: CatalogInput) => Effect.Effect<ReadonlySet<string>, SqlError>;
+/** Only valid, complete covering indexes satisfy the upgrade; failed builds are retried. */
+export declare const readHistoryActivityIndexes: (input: CatalogInput) => Effect.Effect<ReadonlySet<string>, SqlError>;
+export declare const migrate: (input: MigrateInput) => Effect.Effect<{
+    readonly plan: MigrationPlan;
+    readonly result: MigrationResult;
+}, ApplyMigrationError>;