@segmentstream-cloud/ontology 0.22.0 → 0.23.0

package/dist/manifest.d.ts

@@ -13,9 +13,11 @@ import { type SignInOptions, type SignInPolicy } from "./sign-in.js";
  * a relationship with a warehouse-backed end carries `on` and omits `optional` and `onDelete`.
  * Version 6 adds the `countDistinct` measure operator and lets stored entities declare `measures`,
  * whose columns name the stored properties' replication view columns. Version 7 adds the avg, min,
- * max and filtered measure operators and balanceOver on measures.
+ * max and filtered measure operators and balanceOver on measures. Version 8 adds the top-level
+ * `measures`, the measures of the model, written only when the ontology declares some: each combines
+ * measures of entities, named `entity.measure`, with its inputs and its alignment.
  */
-export declare const MANIFEST_VERSION = 7;
+export declare const MANIFEST_VERSION = 8;
 /** The phrase used for a direction the author did not phrase. */
 export declare const DEFAULT_PHRASE = "has";
 export declare const SelectOptionManifest: Schema.Struct<{
@@ -146,6 +148,27 @@ export declare const MeasureManifest: Schema.Struct<{
     readonly balanceOver: Schema.optionalKey<Schema.String>;
 }>;
 export type MeasureManifest = typeof MeasureManifest.Type;
+/**
+ * A measure of the model, `defineOntology({ measures })`. Its expression is an entity measure's
+ * arithmetic whose `measure` nodes name `entity.measure`, with references to other model measures
+ * expanded. Names are wire names throughout.
+ */
+export declare const ModelMeasureManifest: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly label: Schema.String;
+    readonly description: Schema.String;
+    readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+    readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+    readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    /** The entity measures the expression reads, `entity.measure`, each once, in reading order. */
+    readonly inputs: Schema.$Array<Schema.String>;
+    /**
+     * Groups of properties that stand for one another: each names every entity the measure reads,
+     * with a property or `null` for an entity without a counterpart.
+     */
+    readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+}>;
+export type ModelMeasureManifest = typeof ModelMeasureManifest.Type;
 export declare const EntityManifest: Schema.Struct<{
     readonly source: Schema.optionalKey<Schema.Struct<{
         readonly asset: Schema.String;
@@ -438,6 +461,25 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
         readonly key: Schema.String;
         readonly description: Schema.String;
     }>>>;
+    /**
+     * The measures of the model, since version 8. Written only when there are some; absent reads as
+     * none.
+     */
+    readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+        readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+        readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        /** The entity measures the expression reads, `entity.measure`, each once, in reading order. */
+        readonly inputs: Schema.$Array<Schema.String>;
+        /**
+         * Groups of properties that stand for one another: each names every entity the measure reads,
+         * with a property or `null` for an entity without a counterpart.
+         */
+        readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+    }>>>;
 }>, {
     readonly signIn: "sign_in";
 }>;
@@ -589,6 +631,25 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
         readonly key: Schema.String;
         readonly description: Schema.String;
     }>>>;
+    /**
+     * The measures of the model, since version 8. Written only when there are some; absent reads as
+     * none.
+     */
+    readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+        readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+        readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        /** The entity measures the expression reads, `entity.measure`, each once, in reading order. */
+        readonly inputs: Schema.$Array<Schema.String>;
+        /**
+         * Groups of properties that stand for one another: each names every entity the measure reads,
+         * with a property or `null` for an entity without a counterpart.
+         */
+        readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+    }>>>;
 }>, {
     readonly signIn: "sign_in";
 }>, Schema.Struct<{
@@ -731,6 +792,25 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
         readonly key: Schema.String;
         readonly description: Schema.String;
     }>>>;
+    /**
+     * The measures of the model, since version 8. Written only when there are some; absent reads as
+     * none.
+     */
+    readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+        readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+        readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        /** The entity measures the expression reads, `entity.measure`, each once, in reading order. */
+        readonly inputs: Schema.$Array<Schema.String>;
+        /**
+         * Groups of properties that stand for one another: each names every entity the measure reads,
+         * with a property or `null` for an entity without a counterpart.
+         */
+        readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+    }>>>;
 }>]>;
 export type OntologyManifest = typeof OntologyManifest.Type;
 /** Retain the complete document when decoding a persisted or published manifest. */
@@ -833,6 +913,18 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
     }[];
     readonly version: number;
     readonly hash: string;
+    readonly measures?: readonly {
+        readonly name: string;
+        readonly label: string;
+        readonly description: string;
+        readonly unit: "number" | "currency" | "ratio" | "percent";
+        readonly format: "decimal" | "currency" | "percent";
+        readonly expression: Schema.Json;
+        readonly inputs: readonly string[];
+        readonly align: readonly {
+            readonly [x: string]: string | null;
+        }[];
+    }[] | undefined;
     readonly connections?: readonly {
         readonly key: string;
         readonly description: string;
@@ -939,6 +1031,18 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
     }[];
     readonly version: number;
     readonly hash: string;
+    readonly measures?: readonly {
+        readonly name: string;
+        readonly label: string;
+        readonly description: string;
+        readonly unit: "number" | "currency" | "ratio" | "percent";
+        readonly format: "decimal" | "currency" | "percent";
+        readonly expression: Schema.Json;
+        readonly inputs: readonly string[];
+        readonly align: readonly {
+            readonly [x: string]: string | null;
+        }[];
+    }[] | undefined;
     readonly connections?: readonly {
         readonly key: string;
         readonly description: string;
@@ -973,6 +1077,8 @@ export declare function buildManifest(input: {
     readonly roles: ReadonlyArray<Role>;
     readonly signIn: SignInOptions;
     readonly connections?: ReadonlyArray<ResolvedConnection>;
+    /** The measures of the model, resolved to their manifest form. */
+    readonly measures?: ReadonlyArray<ModelMeasureManifest>;
 }): OntologyManifest;
 /** The keys of every connection the manifest's actions call, without duplicates. */
 export declare function actionConnectionKeys(manifest: Pick<OntologyManifest, "entities">): Array<string>;

package/dist/manifest.js

@@ -16,9 +16,11 @@ import { DEFAULT_SIGN_IN_POLICY, isSignInPolicy, } from "./sign-in.js";
  * a relationship with a warehouse-backed end carries `on` and omits `optional` and `onDelete`.
  * Version 6 adds the `countDistinct` measure operator and lets stored entities declare `measures`,
  * whose columns name the stored properties' replication view columns. Version 7 adds the avg, min,
- * max and filtered measure operators and balanceOver on measures.
+ * max and filtered measure operators and balanceOver on measures. Version 8 adds the top-level
+ * `measures`, the measures of the model, written only when the ontology declares some: each combines
+ * measures of entities, named `entity.measure`, with its inputs and its alignment.
  */
-export const MANIFEST_VERSION = 7;
+export const MANIFEST_VERSION = 8;
 /** The first version whose documents use snake_case names on the wire. */
 const WIRE_MANIFEST_VERSION = 4;
 /** The phrase used for a direction the author did not phrase. */
@@ -139,6 +141,26 @@ export const MeasureManifest = Schema.Struct({
      */
     balanceOver: Schema.optionalKey(Schema.String),
 });
+/**
+ * A measure of the model, `defineOntology({ measures })`. Its expression is an entity measure's
+ * arithmetic whose `measure` nodes name `entity.measure`, with references to other model measures
+ * expanded. Names are wire names throughout.
+ */
+export const ModelMeasureManifest = Schema.Struct({
+    name: Schema.String,
+    label: Schema.String,
+    description: Schema.String,
+    unit: Schema.Literals(["number", "currency", "ratio", "percent"]),
+    format: Schema.Literals(["decimal", "currency", "percent"]),
+    expression: Schema.Json,
+    /** The entity measures the expression reads, `entity.measure`, each once, in reading order. */
+    inputs: Schema.Array(Schema.String),
+    /**
+     * Groups of properties that stand for one another: each names every entity the measure reads,
+     * with a property or `null` for an entity without a counterpart.
+     */
+    align: Schema.Array(Schema.Record(Schema.String, Schema.NullOr(Schema.String))),
+});
 export const EntityManifest = Schema.Struct({
     source: Schema.optionalKey(Schema.Struct({
         asset: Schema.String,
@@ -200,6 +222,11 @@ const OntologyManifestModel = Schema.Struct({
     signIn: Schema.optionalKey(SignInManifest),
     /** The connections the actions call. Written only when there are some; absent reads as none. */
     connections: Schema.optionalKey(Schema.Array(ConnectionManifest)),
+    /**
+     * The measures of the model, since version 8. Written only when there are some; absent reads as
+     * none.
+     */
+    measures: Schema.optionalKey(Schema.Array(ModelMeasureManifest)),
 });
 const PropertyManifestWire = PropertyManifest.pipe(Schema.encodeKeys({
     renamedFrom: "renamed_from",
@@ -429,6 +456,7 @@ function entityManifest(input) {
 /** Builds the manifest of a resolved ontology that passed `check`. */
 export function buildManifest(input) {
     const connections = input.connections ?? [];
+    const measures = input.measures ?? [];
     const warehouseBacked = new Set(input.entities
         .filter((candidate) => candidate.entity.definition.source !== undefined)
         .map((candidate) => candidate.name));
@@ -450,6 +478,7 @@ export function buildManifest(input) {
                 })),
             }
             : {}),
+        ...(measures.length > 0 ? { measures } : {}),
     };
     return { ...body, hash: manifestHash(encodeManifest({ ...body, hash: "" })) };
 }

package/dist/measure.d.ts

@@ -71,12 +71,62 @@ export type Measure = MeasureExpression & Partial<MeasureOptions> & {
     readonly where?: ReadonlyArray<MeasureCondition | MeasureColumnCondition>;
     /** An aggregate's balance property, as its builder's `balanceOver` option declares it. */
     readonly balanceOver?: string;
+    /** A measure of an entity reads that entity's rows only: alignment is for model measures. */
+    readonly align?: never;
 };
 export type Measures = Readonly<Record<string, Measure>>;
+/**
+ * One group of a model measure's alignment: every entity the measure reads, by its TypeScript name,
+ * with its property that stands for the others', or `null` when the entity has no counterpart, as a
+ * current snapshot has no date.
+ */
+export type AlignmentGroup = Readonly<Record<string, string | null>>;
+/** The options of a model measure: a measure's options and how its entities' properties align. */
+export interface ModelMeasureOptions extends MeasureOptions {
+    /**
+     * At most 5 groups of properties that stand for one another across the entities the measure
+     * reads, such as a sales date and a plan month. A request that groups or filters by one member of
+     * a group reads each entity through its own member. Properties of one group share a type, and a
+     * property appears in one group at most.
+     */
+    readonly align?: ReadonlyArray<AlignmentGroup>;
+}
+/**
+ * A measure of the model, declared in `defineOntology({ measures })`: arithmetic over measures of
+ * entities, `m.ref("entity.measure")`, and over other model measures, `m.ref("name")`. It reads
+ * entity measures and aggregates no rows of its own.
+ */
+export type ModelMeasure = MeasureExpression & Partial<MeasureOptions> & {
+    readonly align?: ReadonlyArray<AlignmentGroup>;
+};
+export type ModelMeasures = Readonly<Record<string, ModelMeasure>>;
+/** A model measure's options that declare an alignment, which only model measures take. */
+type AlignedOptions = ModelMeasureOptions & {
+    readonly align: ReadonlyArray<AlignmentGroup>;
+};
+/**
+ * An argument of arithmetic: any expression but one that declares an alignment, which belongs on
+ * the model measure itself.
+ */
+type Argument = MeasureExpression & {
+    readonly align?: never;
+};
+/** Arithmetic of two expressions; with `align` among its options, a model measure. */
+interface Arithmetic {
+    (left: Argument, right: Argument, options: AlignedOptions): ModelMeasure;
+    (left: Argument, right: Argument, options?: MeasureOptions): Measure;
+}
+/** A reference to another measure; with `align` among its options, a model measure. */
+interface Reference {
+    (name: string, options: AlignedOptions): ModelMeasure;
+    (name: string, options?: MeasureOptions): Measure;
+}
 /**
  * Arithmetic combines aggregates; references name another measure 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.
+ * and `balanceOver`, the date its rows are snapshots over. In `defineOntology({ measures })`,
+ * references name measures of entities, `m.ref("sales.revenue")`, or other model measures, and
+ * arithmetic and references take `align`.
  */
 export declare const m: {
     readonly count: (options?: AggregateOptions) => Measure;
@@ -93,12 +143,12 @@ export declare const m: {
     readonly min: (property: string, options?: AggregateOptions) => Measure;
     /** The greatest value of an integer or number property. Maximums do not add up. */
     readonly max: (property: string, options?: AggregateOptions) => Measure;
-    readonly ref: (name: string, options?: MeasureOptions) => Measure;
+    readonly ref: Reference;
     readonly literal: (value: number | string, options?: MeasureOptions) => Measure;
-    readonly add: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
-    readonly subtract: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
-    readonly multiply: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
-    readonly divide: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
+    readonly add: Arithmetic;
+    readonly subtract: Arithmetic;
+    readonly multiply: Arithmetic;
+    readonly divide: Arithmetic;
 };
 /** The conditions an expression declares: an aggregate's `where` option, or a `filtered` node's. */
 export declare function conditionsOf(value: Measure | MeasureExpression): ReadonlyArray<MeasureCondition | MeasureColumnCondition> | undefined;
@@ -119,3 +169,4 @@ export declare function conditionProperty(condition: object): unknown;
  * naming columns too.
  */
 export declare function measureExpression(value: MeasureExpression, columns: ReadonlyMap<string, string>): MeasureExpression;
+export {};

package/dist/measure.js

@@ -3,6 +3,9 @@ export const MEASURE_AGGREGATES = ["count", "sum", "countDistinct", "avg", "min"
 function binary(op) {
     return (left, right, options) => ({ op, args: [left, right], ...options });
 }
+function reference(name, options) {
+    return { op: "measure", name, ...options };
+}
 /** An aggregate of one property of the entity. */
 function aggregate(op) {
     return (property, options) => ({
@@ -14,7 +17,9 @@ function aggregate(op) {
 /**
  * Arithmetic combines aggregates; references name another measure 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.
+ * and `balanceOver`, the date its rows are snapshots over. In `defineOntology({ measures })`,
+ * references name measures of entities, `m.ref("sales.revenue")`, or other model measures, and
+ * arithmetic and references take `align`.
  */
 export const m = {
     count: (options) => ({ op: "count", ...options }),
@@ -31,7 +36,7 @@ export const m = {
     min: aggregate("min"),
     /** The greatest value of an integer or number property. Maximums do not add up. */
     max: aggregate("max"),
-    ref: (name, options) => ({ op: "measure", name, ...options }),
+    ref: reference,
     literal: (value, options) => ({
         op: "literal",
         value: String(value),

package/dist/migrate/model.d.ts

@@ -161,6 +161,16 @@ export declare const MigrationPlan: Schema.Struct<{
             readonly key: Schema.String;
             readonly description: Schema.String;
         }>>>;
+        readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly label: Schema.String;
+            readonly description: Schema.String;
+            readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+            readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+            readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly inputs: Schema.$Array<Schema.String>;
+            readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+        }>>>;
     }>, {
         readonly signIn: "sign_in";
     }>, Schema.Struct<{
@@ -267,6 +277,16 @@ export declare const MigrationPlan: Schema.Struct<{
             readonly key: Schema.String;
             readonly description: Schema.String;
         }>>>;
+        readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly label: Schema.String;
+            readonly description: Schema.String;
+            readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+            readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+            readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly inputs: Schema.$Array<Schema.String>;
+            readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+        }>>>;
     }>]>;
     /** Non-transactional steps first, then the steps of the one transaction, in execution order. */
     readonly steps: Schema.$Array<Schema.Struct<{

package/dist/model-measures.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedEntity } from "./analyze.js";
+import type { Diagnostic, DiagnosticCode } from "./diagnostics.js";
+import type { ModelMeasureManifest } from "./manifest.js";
+type Report = (code: DiagnosticCode, path: string, message: string, severity?: Diagnostic["severity"]) => void;
+/** The most measures a model declares. */
+export declare const MAXIMUM_MODEL_MEASURES = 50;
+/** The most distinct entity measures one model measure reads, references expanded. */
+export declare const MAXIMUM_MODEL_MEASURE_INPUTS = 10;
+/** The most alignment groups one model measure declares. */
+export declare const MAXIMUM_ALIGNMENT_GROUPS = 5;
+/**
+ * Resolves and checks the measures of the model, `defineOntology({ measures })`, against the
+ * resolved entities, whose measures were checked first (docs/ontology-aggregates-release-3-spec.md,
+ * "Declaring model measures"). Returns the manifest form of each measure that passed, in declaration
+ * order: references expanded, names on the wire, inputs in reading order.
+ */
+export declare function resolveModelMeasures(input: {
+    readonly measures: unknown;
+    readonly entities: ReadonlyArray<ResolvedEntity>;
+    readonly report: Report;
+}): ReadonlyArray<ModelMeasureManifest>;
+export {};