@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/property.js

@@ -0,0 +1,301 @@
+import { Schema } from "effect";
+import { humanize } from "./names.js";
+import { BlobValue, MAX_BLOB_BYTES } from "./blob.js";
+import { nameToWire } from "./authoring-names.js";
+/** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
+export const PROPERTY_TYPES = [
+    "text",
+    "email",
+    "url",
+    "integer",
+    "number",
+    "boolean",
+    "date",
+    "timestamp",
+    "select",
+    "json",
+    "blob",
+    "list",
+];
+/** Schema annotation that carries a property's storage metadata. */
+export const PROPERTY_ANNOTATION = "segmentstream/ontology/property";
+/**
+ * Schema annotation that marks a record reference in an action input. It is emitted into the input's
+ * JSON Schema so that consumers can offer a record picker.
+ */
+export const REFERENCE_ANNOTATION = "x-ontology-ref";
+/**
+ * An email address: a local part, one `@`, and a domain of dot-separated labels. The labels exclude
+ * the dot that separates them, so no two parts of the pattern can match the same characters and it
+ * runs in linear time on any input.
+ */
+export const EMAIL_PATTERN = /^[^\s@]+@[^\s@.]+(?:\.[^\s@.]+)+$/;
+const URL_PATTERN = /^https?:\/\/\S+$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** The options every property constructor takes. */
+const COMMON_OPTIONS = [
+    "column",
+    "scope",
+    "optional",
+    "default",
+    "unique",
+    "label",
+    "description",
+    "renamedFrom",
+    "managed",
+    "display",
+];
+/** The options a constructor takes beyond {@link COMMON_OPTIONS}, by property type. */
+const TYPE_OPTIONS = {
+    text: ["maxLength"],
+    integer: ["min", "max"],
+    number: ["min", "max"],
+    blob: ["accept", "maxBytes"],
+};
+const unknownOptions = new WeakMap();
+/**
+ * The options a property was given that its constructor does not take, such as `minimum` for
+ * `p.integer`, which takes `min`. TypeScript refuses them in a literal; `check` reports them for
+ * code that is evaluated without type checking.
+ */
+export function unknownPropertyOptions(value) {
+    return (typeof value === "object" || typeof value === "function") && value !== null
+        ? (unknownOptions.get(value) ?? [])
+        : [];
+}
+/** Keeps the unknown options of a property on the schema the SDK rebuilt it as. */
+export function inheritUnknownOptions(from, to) {
+    const unknown = unknownPropertyOptions(from);
+    if (unknown.length > 0 && (typeof to === "object" || typeof to === "function") && to !== null) {
+        unknownOptions.set(to, unknown);
+    }
+}
+/** What a constructor takes, for the message that names an unknown option. */
+export function propertyOptionNames(type) {
+    return [...COMMON_OPTIONS, ...(TYPE_OPTIONS[type] ?? [])];
+}
+function construct({ type, base, options, checks = [], format, selectOptions, items, }) {
+    const definition = {
+        type,
+        ...(options.column !== undefined ? { column: options.column } : {}),
+        ...(options.scope !== undefined ? { scope: options.scope } : {}),
+        optional: options.optional === true,
+        unique: options.unique === true,
+        managed: options.managed === true,
+        ...(options.default !== undefined ? { default: options.default } : {}),
+        ...(options.label !== undefined ? { label: options.label } : {}),
+        ...(options.description !== undefined ? { description: options.description } : {}),
+        ...(options.renamedFrom !== undefined ? { renamedFrom: options.renamedFrom } : {}),
+        ...(options.display !== undefined ? { display: options.display } : {}),
+        ...(options.min !== undefined ? { min: options.min } : {}),
+        ...(options.max !== undefined ? { max: options.max } : {}),
+        ...(options.maxLength !== undefined ? { maxLength: options.maxLength } : {}),
+        ...(options.accept !== undefined ? { accept: options.accept } : {}),
+        ...(options.maxBytes !== undefined ? { maxBytes: options.maxBytes } : {}),
+        ...(selectOptions !== undefined ? { options: selectOptions } : {}),
+        ...(items !== undefined ? { items } : {}),
+    };
+    // Annotations go on the base node, before the checks, so that the JSON Schema keeps them at the top
+    // level and readers find the definition in `ast.annotations`.
+    const annotated = base.annotate({
+        ...(options.label !== undefined ? { title: options.label } : {}),
+        ...(options.description !== undefined ? { description: options.description } : {}),
+        ...(format !== undefined ? { format } : {}),
+        [PROPERTY_ANNOTATION]: definition,
+    });
+    const [firstCheck, ...otherChecks] = checks;
+    const checked = firstCheck === undefined ? annotated : annotated.check(firstCheck, ...otherChecks);
+    const result = definition.optional ? Schema.optionalKey(checked) : checked;
+    const allowed = new Set(propertyOptionNames(type));
+    const unknown = Object.keys(options).filter((key) => !allowed.has(key));
+    if (unknown.length > 0) {
+        unknownOptions.set(result, unknown);
+        unknownOptions.set(checked, unknown);
+    }
+    return result;
+}
+function rangeChecks(options) {
+    return [
+        ...(options.min !== undefined ? [Schema.isGreaterThanOrEqualTo(options.min)] : []),
+        ...(options.max !== undefined ? [Schema.isLessThanOrEqualTo(options.max)] : []),
+    ];
+}
+function text(options) {
+    const settings = options ?? {};
+    const checks = settings.maxLength !== undefined ? [Schema.isMaxLength(settings.maxLength)] : [];
+    return construct({ type: "text", base: Schema.String, options: settings, checks });
+}
+function email(options) {
+    return construct({
+        type: "email",
+        base: Schema.String,
+        options: options ?? {},
+        checks: [Schema.isPattern(EMAIL_PATTERN)],
+        format: "email",
+    });
+}
+function url(options) {
+    return construct({
+        type: "url",
+        base: Schema.String,
+        options: options ?? {},
+        checks: [Schema.isPattern(URL_PATTERN)],
+        format: "uri",
+    });
+}
+function integer(options) {
+    const settings = options ?? {};
+    return construct({
+        type: "integer",
+        base: Schema.Int,
+        options: settings,
+        checks: rangeChecks(settings),
+    });
+}
+function number(options) {
+    const settings = options ?? {};
+    return construct({
+        type: "number",
+        base: Schema.Finite,
+        options: settings,
+        checks: rangeChecks(settings),
+    });
+}
+function boolean(options) {
+    return construct({ type: "boolean", base: Schema.Boolean, options: options ?? {} });
+}
+/** A calendar date as `YYYY-MM-DD`. */
+function date(options) {
+    return construct({
+        type: "date",
+        base: Schema.String,
+        options: options ?? {},
+        checks: [Schema.isPattern(DATE)],
+        format: "date",
+    });
+}
+/** An instant as an ISO 8601 string with a time zone, for example `2026-10-04T09:30:00Z`. */
+function timestamp(options) {
+    return construct({
+        type: "timestamp",
+        base: Schema.String,
+        options: options ?? {},
+        checks: [Schema.isPattern(TIMESTAMP)],
+        format: "date-time",
+    });
+}
+/**
+ * One of a closed set of described values. Each option becomes its own JSON Schema branch with its
+ * label as `title` and its description, so that agents see what every value means.
+ */
+function select(options, settings) {
+    const selectOptions = options.map((option) => {
+        if (typeof option === "string") {
+            return { value: option, label: humanize(option) };
+        }
+        return {
+            value: option.value,
+            label: option.label ?? humanize(option.value),
+            description: option.description,
+        };
+    });
+    const members = selectOptions.map((option) => Schema.Literal(option.value).annotate({
+        title: option.label,
+        ...(option.description !== undefined ? { description: option.description } : {}),
+    }));
+    return construct({
+        type: "select",
+        base: Schema.Union(members),
+        options: settings ?? {},
+        selectOptions,
+    });
+}
+/** Any JSON value. */
+function json(options) {
+    return construct({ type: "json", base: Schema.Json, options: options ?? {} });
+}
+/**
+ * A reference to a record of an entity, by id, for action inputs. Relationships between entities
+ * are declared with `rel.one` and `rel.many`, not with references.
+ */
+function ref(target, options) {
+    const entityName = typeof target === "string" ? target : target.name;
+    const settings = options ?? {};
+    const schema = Schema.String.annotate({
+        ...(settings.label !== undefined ? { title: settings.label } : {}),
+        description: settings.description ?? `The id of a ${entityName} record.`,
+        format: "uuid",
+        [REFERENCE_ANNOTATION]: nameToWire(entityName),
+    }).check(Schema.isPattern(UUID));
+    return (settings.optional === true ? Schema.optionalKey(schema) : schema);
+}
+function blob(options) {
+    const settings = options ?? {};
+    return construct({
+        type: "blob",
+        base: BlobValue,
+        options: {
+            ...settings,
+            accept: settings.accept ?? ["*/*"],
+            maxBytes: settings.maxBytes ?? MAX_BLOB_BYTES,
+        },
+    });
+}
+/**
+ * A list of values of one property type, read-only and kept by the platform. Only the built-in
+ * `User` has one, `roles`, which the runtime reads from the role assignments beside the table:
+ * `check` refuses a list on any other entity, so no table has an array column and no action
+ * writes one. Filters take `has` and `hasAny`; a list cannot be sorted on.
+ */
+function list(item, options) {
+    const itemType = propertyDefinition(item)?.type ?? "text";
+    return construct({
+        type: "list",
+        base: Schema.Array(item),
+        options,
+        items: itemType,
+    });
+}
+export const p = {
+    text,
+    email,
+    url,
+    integer,
+    number,
+    boolean,
+    date,
+    timestamp,
+    select,
+    json,
+    blob,
+    list,
+    ref,
+};
+function findAnnotation(ast, key) {
+    if (ast.annotations !== undefined && key in ast.annotations) {
+        return ast.annotations[key];
+    }
+    for (const check of ast.checks ?? []) {
+        if (check.annotations !== undefined && key in check.annotations) {
+            return check.annotations[key];
+        }
+    }
+    return undefined;
+}
+/** The storage metadata of a schema built with a `p.*` constructor, or `undefined` for any other value. */
+export function propertyDefinition(value) {
+    if (!Schema.isSchema(value)) {
+        return undefined;
+    }
+    return findAnnotation(value.ast, PROPERTY_ANNOTATION);
+}
+/** The entity a `p.ref` schema points at, or `undefined` for any other value. */
+export function referenceTarget(value) {
+    if (!Schema.isSchema(value)) {
+        return undefined;
+    }
+    const target = findAnnotation(value.ast, REFERENCE_ANNOTATION);
+    return typeof target === "string" ? target : undefined;
+}

package/dist/query.d.ts

@@ -0,0 +1,245 @@
+import { Schema } from "effect";
+import type { JsonSchemaObject } from "./analyze.js";
+import { type EntityManifest, type OntologyManifest } from "./manifest.js";
+import type { PropertyType } from "./property.js";
+/** How a record field is stored: a property type, or a UUID for ids and `<relationship>_id` keys. */
+export type StorageType = PropertyType | "uuid";
+/**
+ * The query language of `find` and of the HTTP API's list and query endpoints.
+ *
+ * ```json
+ * {
+ *   "where": {
+ *     "status": { "in": ["new", "contacted"] },
+ *     "owner": { "email": { "eq": "ada@example.com" } },
+ *     "tags": { "some": { "name": { "eq": "priority" } } },
+ *     "or": [{ "fitScore": { "gte": 80 } }, { "source": "pilot_request" }]
+ *   },
+ *   "orderBy": [{ "field": "created_at", "direction": "desc" }],
+ *   "include": ["owner"],
+ *   "limit": 50
+ * }
+ * ```
+ *
+ * {@link Query} checks the structure for any entity; {@link entityQuerySchema} builds the precise
+ * schema of one entity from the manifest, with its fields, their operators and its relationships.
+ * The runtime validates every query with the precise schema. `include` also takes the object form
+ * `{ "owner": true }`, which a list of names decodes into.
+ */
+export declare const DEFAULT_QUERY_LIMIT = 50;
+export declare const MAX_QUERY_LIMIT = 200;
+/** The most values an `in` filter takes. */
+export declare const MAX_IN_VALUES = 1000;
+/** Filter operators. A field's type decides which apply; see {@link entityQuerySchema}. */
+export declare const FILTER_OPERATORS: readonly ["eq", "ne", "in", "isNull", "contains", "startsWith", "gt", "gte", "lt", "lte", "between"];
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+/** Filter operators of a list field: it holds the value, or any of the values. */
+export declare const LIST_FILTER_OPERATORS: readonly ["has", "hasAny"];
+export type ListFilterOperator = (typeof LIST_FILTER_OPERATORS)[number];
+/** Combinators of a `where`. They take the place of field names. */
+export declare const WHERE_COMBINATORS: readonly ["and", "or", "not"];
+/** Quantifiers of a filter on a to-many relationship. */
+export declare const MANY_QUANTIFIERS: readonly ["some", "none", "every"];
+/**
+ * Conditions on one field; all of them must hold. `ne` matches records where the field is empty;
+ * `contains` and `startsWith` ignore case; `between` includes both ends. In a `where`, a bare value
+ * stands for `{ eq: value }` and `null` for `{ isNull: true }`. A list field takes only `has` and
+ * `hasAny`.
+ */
+export interface FieldFilter {
+    readonly eq?: Schema.Json;
+    readonly ne?: Schema.Json;
+    readonly in?: ReadonlyArray<Schema.Json>;
+    readonly isNull?: boolean;
+    readonly contains?: string;
+    readonly startsWith?: string;
+    readonly gt?: number | string;
+    readonly gte?: number | string;
+    readonly lt?: number | string;
+    readonly lte?: number | string;
+    readonly between?: readonly [number | string, number | string];
+    /** A list field holds the value. */
+    readonly has?: string;
+    /** A list field holds at least one of the values; none matches nothing. */
+    readonly hasAny?: ReadonlyArray<string>;
+}
+/** A filter on a to-many relationship: some, none or every related record matches. */
+export interface ManyFilter {
+    readonly some?: Where;
+    readonly none?: Where;
+    readonly every?: Where;
+}
+/**
+ * Conditions on a record, all of which must hold: field filters by field name, relationship
+ * filters by relationship name (a `where` on the target for to-one, a {@link ManyFilter} for
+ * to-many), and the `and`, `or` and `not` combinators.
+ */
+export interface Where {
+    readonly and?: ReadonlyArray<Where>;
+    readonly or?: ReadonlyArray<Where>;
+    readonly not?: Where;
+    readonly [field: string]: FieldFilter | ManyFilter | Where | ReadonlyArray<Where> | Schema.Json | undefined;
+}
+export declare const SortDirection: Schema.Literals<readonly ["asc", "desc"]>;
+export type SortDirection = typeof SortDirection.Type;
+export declare const OrderBy: Schema.Struct<{
+    readonly field: Schema.String;
+    readonly direction: Schema.optionalKey<Schema.Literals<readonly ["asc", "desc"]>>;
+}>;
+export type OrderBy = typeof OrderBy.Type;
+/** The relationships to include, once decoded: `{ owner: true, tags: true }`. */
+export type Included = {
+    readonly [relationship: string]: true;
+};
+/** Whether an `include` is the list form, `["owner", "tags"]`. */
+export declare function isIncludeList<L extends string>(include: ReadonlyArray<L> | object): include is ReadonlyArray<L>;
+/** The relationship names an `include` lists, in either form. */
+export declare function includedRelationships(include: Query["include"]): ReadonlyArray<string>;
+/** A query on any entity. The runtime checks the fields against the entity. */
+export declare const Query: Schema.Struct<{
+    readonly where: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly orderBy: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly field: Schema.String;
+        readonly direction: Schema.optionalKey<Schema.Literals<readonly ["asc", "desc"]>>;
+    }>>>;
+    readonly select: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly include: Schema.optionalKey<Schema.Codec<Included, readonly string[] | Included, never, never>>;
+    readonly after: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+/**
+ * A query. `where` follows {@link Where}; `include` adds related records by relationship name, as a
+ * list, `["owner", "tags"]`, or as an object, `{ owner: true, tags: true }`.
+ */
+export interface Query {
+    readonly where?: Where;
+    readonly orderBy?: ReadonlyArray<OrderBy>;
+    /** Base-record fields to return. The id is always returned; includes remain separate. */
+    readonly select?: ReadonlyArray<string>;
+    readonly include?: ReadonlyArray<string> | Included;
+    readonly after?: string;
+    readonly limit?: number;
+}
+/** A page of records. `nextCursor` is `null` on the last page. */
+export interface QueryResult<R> {
+    readonly items: ReadonlyArray<R>;
+    readonly nextCursor: string | null;
+    /** Present only for an explicitly projected record query. */
+    readonly projected?: true;
+}
+/** A page of records of any entity. */
+export declare const QueryResult: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+    readonly projected: Schema.optionalKey<Schema.Literal<true>>;
+}>;
+/** A page of records described by `record`. */
+export declare function queryResultSchema<S extends Schema.Top>(record: S): Schema.Struct<{
+    readonly items: Schema.$Array<S>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+}>;
+/** Full pages keep their complete record contract; projections carry an explicit marker. */
+export declare function projectedQueryResultSchema(record: Schema.Top, projection: Schema.Top, wire?: boolean): Schema.Union<readonly [Schema.encodeKeys<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Top>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+    readonly projected: Schema.optionalKey<Schema.Never>;
+}>, {
+    readonly nextCursor: "next_cursor";
+}>, Schema.encodeKeys<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Top>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+    readonly projected: Schema.Literal<true>;
+}>, {
+    readonly nextCursor: "next_cursor";
+}>] | readonly [Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Top>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+    readonly projected: Schema.optionalKey<Schema.Never>;
+}>, Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Top>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+    readonly projected: Schema.Literal<true>;
+}>]>;
+/** A field a query can filter and sort on: a system field, a property, or a `<relationship>_id`. */
+export interface QueryField {
+    readonly name: string;
+    readonly storage: StorageType;
+    readonly nullable: boolean;
+    /** The values of a `select` property. */
+    readonly options?: ReadonlyArray<string>;
+}
+/**
+ * A relationship as seen from one entity: declared on it, or the inverse of a relationship another
+ * entity declares. `rel.one` is to-one from its declaring side; every inverse and `rel.many` is
+ * to-many.
+ */
+export interface QueryLink {
+    /** The name on this entity: `owner`, `tags`, or an inverse such as `notes`. */
+    readonly name: string;
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+    /** The entity that declares the relationship, and its name there. */
+    readonly declaredBy: string;
+    readonly relationship: string;
+    /** Whether the declaration is `rel.one` or `rel.many`. */
+    readonly declared: "one" | "many";
+    readonly inverse: boolean;
+}
+/**
+ * The fields of an entity's records, in record order. A value-matched relationship has no
+ * `<relationship>_id`: its reference is the property named in `on`.
+ */
+export declare function queryFields(entity: EntityManifest): ReadonlyArray<QueryField>;
+/** The relationships of an entity, declared ones first, then the inverses landing on it. */
+export declare function queryLinks(manifest: OntologyManifest, entityName: string, warehouseRecords?: boolean): ReadonlyArray<QueryLink>;
+export declare function findEntityManifest(manifest: OntologyManifest, entityName: string): EntityManifest | undefined;
+/** `YYYY-MM-DD` naming a day that exists. */
+export declare function isCalendarDate(value: string): boolean;
+/** An ISO 8601 instant with a time zone, on a day that exists. PostgreSQL keeps microseconds. */
+export declare function isInstant(value: string): boolean;
+export declare function isUuid(value: string): boolean;
+/** The schema of one value of a field, as filters and cursors carry it. */
+export declare function fieldValueSchema(field: QueryField): Schema.Top;
+/** Fields a query can sort on: every field but `json`, `blob` and `list` properties. */
+export declare function isOrderable(field: QueryField): boolean;
+/**
+ * Whether a value is a filter the field takes, as a query's `where` would accept it: operators by
+ * their query names, each with an operand of the field's type, or a bare value or `null`.
+ */
+export declare function isFieldFilterOf(field: QueryField, value: unknown): boolean;
+/** The parts of an entity's query, for APIs that take them apart, such as URL parameters. */
+export interface EntityQuerySchemas {
+    readonly where: Schema.Codec<Where>;
+    readonly orderBy: Schema.Codec<ReadonlyArray<OrderBy>>;
+    readonly select: Schema.Codec<ReadonlyArray<string>>;
+    readonly include: Schema.Codec<Included, ReadonlyArray<string> | Included>;
+    readonly limit: Schema.Codec<number>;
+    readonly after: Schema.Codec<string>;
+    readonly query: Schema.Codec<Query>;
+}
+/**
+ * The precise query schemas of one entity: its fields with the operators of their types, its
+ * relationships (declared and inverse), the fields it can sort on and the relationships it can
+ * include. Every struct is closed: an unknown field, operator or key is an issue whatever the parse
+ * options, never a silently ignored filter.
+ */
+export declare function entityQuerySchemas(manifest: OntologyManifest, entityName: string, wire?: boolean, warehouseRecords?: boolean): EntityQuerySchemas;
+/** The query schema of one entity; see {@link entityQuerySchemas}. */
+export declare function entityQuerySchema(manifest: OntologyManifest, entityName: string, warehouseRecords?: boolean): Schema.Codec<Query>;
+/**
+ * The record of an entity as the runtime returns it: system fields, properties (`null` when empty;
+ * dates as `YYYY-MM-DD`, timestamps as ISO 8601 in UTC) and a `<relationship>_id` per `rel.one`. It
+ * checks the shape of stored values, not the refinements of the definition (`maxLength`, `min`,
+ * patterns), so that tightening a refinement never makes existing records unreadable.
+ */
+export declare function entityRecordSchema(entity: EntityManifest): Schema.Codec<JsonRecord>;
+/** A record as JSON, as the runtime returns it and the HTTP API sends it. */
+export type JsonRecord = {
+    readonly [field: string]: Schema.Json;
+};
+/** A page of an entity's records, with the relationships a query may include. */
+export declare function entityQueryResultSchema(manifest: OntologyManifest, entityName: string, wire?: boolean, warehouseRecords?: boolean): Schema.Codec<QueryResult<JsonRecord>, unknown>;
+/** The JSON Schema (draft 2020-12) of an entity's queries, for MCP tools, OpenAPI and the console. */
+export declare function queryJsonSchema(manifest: OntologyManifest, entityName: string, warehouseRecords?: boolean): JsonSchemaObject;
+/** The JSON Schema (draft 2020-12) of a page of an entity's records. */
+export declare function queryResultJsonSchema(manifest: OntologyManifest, entityName: string): JsonSchemaObject;