@edgerules/portable 0.0.0-alpha.202607041229

package/dist/portable.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Portable JSON format for EdgeRules.
+ *
+ * This file ships with EdgeRules and is the TypeScript contract a host / GUI uses to:
+ *   1. read the model using:
+ *      - `service.get(path, filter?): PortableNode | PortableError`
+ *      - `service.get("*", filter?): PortableRootContext | PortableError`
+ *   2. set new entities to the model using:
+ *      - `service.set(path, PortableNode): PortableNode | PortableError`
+ *
+ * Filters select which view of an entry is returned:
+ *  - "CONTEXT" (default) — runtime/data view: contexts, values, expressions, and function *schemas*.
+ *  - "TYPE_DEFINITIONS" — type definitions only.
+ *  - "FUNCTION_DEFINITIONS" — function definitions (parameters + body) only.
+ *  - "ALL" — every view combined (context, type, and function definitions).
+ *
+ * On success the returned node is enriched with linked type information; otherwise a PortableError is returned.
+ */
+/**
+ * JSON-serializable scalars only. Temporal values (date/time/datetime/duration/period) are not
+ * native JSON, so they travel as a PortableExpressionString — e.g. "date('2024-01-15')" or
+ * "duration('P4D')" — consistent with the Output EBNF `TemporalValue` constructors.
+ */
+export type PortableScalar = string | number | boolean;
+/**
+ * Any concrete JSON value a Portable data field may hold: a scalar, an array, an object, or an
+ * EdgeRules expression carried as a string.
+ */
+export type PortableValue = PortableScalar | PortableValue[] | PortableContext | PortableExpressionString;
+export type PortableTypeReference = 'number' | 'string' | 'boolean' | 'date' | 'time' | 'datetime' | 'duration' | 'period' | 'array' | (string & {});
+/**
+ * An EdgeRules expression carried as a string, e.g. "applicant.income >= 30000".
+ *
+ * The EdgeRules DSL parser reads the string and parses it by these rules:
+ *   "'John'"                    -> parsed as a string literal
+ *   "applicant.income >= 30000" -> parsed as an expression
+ *   "[1,2,3]"                   -> parsed as an array via expression parsing, but prefer a
+ *                                  real JSON array [1,2,3] (a PortableValue), which is treated
+ *                                  as data instead of DSL.
+ */
+export type PortableExpressionString = string;
+export interface PortableObject {
+    '@kind': string;
+    '@description'?: string;
+}
+/**
+ * A type node (`@kind: 'type'`): used as a typed hole / input slot in a context, a field in a
+ * type definition, an array element type (`items`), or a parameter/return type. Carries the
+ * declared `type` plus optional input metadata (`required`, `default`, `enum`, `writeOnly`).
+ * The input-metadata fields are meaningful only where the node is an input or type-definition
+ * field; they are ignored when it appears as a `@return` / `@parameters` descriptor.
+ */
+export interface PortableTypedValue extends PortableObject {
+    '@kind': 'type';
+    /**
+     * The value's type: a scalar type name, the literal `'array'` for list types
+     * (the element type lives in `items`), or a user-defined type name (e.g. "Customer").
+     */
+    type: PortableTypeReference;
+    /**
+     * Every input is expected: an absent input yields a `Missing` special value.
+     * `required: true` is an additional validation — a supplied value that fails the
+     * requirement yields an `Invalid` special value. Mirrors JSON Schema / OpenAPI `required`.
+     */
+    required?: boolean;
+    /**
+     * True for input fields the host supplies: typed holes (e.g. `<boolean>`,
+     * `<number, required: true>`). These are write-only slots — the host provides
+     * a value, the engine never computes one. Mirrors OpenAPI `writeOnly`.
+     */
+    writeOnly?: boolean;
+    /**
+     * True for computed (engine-derived) data-context fields: constants and
+     * expressions the host must not supply. Mirrors OpenAPI `readOnly`.
+     * `readOnly` and `writeOnly` are mutually exclusive — a data-context leaf
+     * carries exactly one. Absent on type-definition fields and on
+     * `@parameters` / `@return` / `items` type references.
+     */
+    readOnly?: boolean;
+    /** Default applied when an optional input is missing. */
+    default?: PortableScalar | PortableScalar[];
+    /** Allowed values; supports string and numeric enums (scalar types only). */
+    enum?: PortableScalar[];
+    /** Element type node; present (and meaningful) only when `type` is "array". */
+    items?: PortableTypedValue | PortableTypeReference;
+}
+/**
+ * The value of any field inside a context node. Reserved `@`-prefixed keys carry
+ * string|number metadata (see the index signature below); all other keys hold a PortableNode.
+ */
+export type PortableNode = PortableValue | PortableContext | PortableContext[] | PortableExpression | PortableTypedValue | PortableFunctionDefinition | PortableTypeDefinition | PortableInvocationDefinition;
+/**
+ * A context node — the model's record/object construct. In EdgeRules a record literal *is* a
+ * context, so data records and model contexts are one and the same node.
+ *
+ * a plain JSON object with no `@kind` defaults to a context
+ */
+export interface PortableContext {
+    '@kind'?: 'context';
+    '@description'?: string;
+    /**
+     * The `string | number` arm admits the reserved `@`-prefixed metadata keys (`@kind`,
+     * `@description`, and `@version` / `@model-name` on `PortableRootContext`); every other key is
+     * a field whose value is a PortableNode.
+     */
+    [key: string]: PortableNode | string | number | undefined;
+}
+export interface PortableRootContext extends PortableContext {
+    '@version'?: string | number;
+    '@model-name'?: string;
+}
+/**
+ * An expression node (`@kind: 'expression'`): a host-authored computed field.
+ * On set, provide only `@kind` and `expression`. On get, the engine adds the linked result
+ * `type` (and `items` for array results) and marks the node `readOnly`.
+ */
+export interface PortableExpression extends PortableObject {
+    '@kind': 'expression';
+    expression: PortableValue;
+    /** Engine-supplied on get; omit on set. */
+    readOnly?: true;
+    /** Inferred (linked) type; engine-supplied on get, omitted on set. */
+    type?: PortableTypeReference;
+    /** Inferred element type when the result type is 'array'; get-only. */
+    items?: PortableTypedValue | PortableTypeReference;
+}
+/**
+ * Used for type definitions.
+ * The fields are either type assignments (for primitive types and arrays) or nested type definitions (for objects).
+ *
+ * Example EdgeRules DSL: `type Customer: { name: <string>; birthdate: <date>; income: <number, 0> }`
+ * is represented as:
+ *  { '@kind': 'type-definition',
+ *      name: { '@kind': 'type', type: 'string' },
+ *      birthdate: { '@kind': 'type', type: 'date' },
+ *      income: { '@kind': 'type', type: 'number', default: 0 }
+ *  }
+ */
+export interface PortableTypeDefinition extends PortableObject {
+    '@kind': 'type-definition';
+    /** The `string` arm admits the reserved `@kind` discriminant; every other key is a field node. */
+    [field: string]: PortableTypedValue | PortableTypeDefinition | string | undefined;
+}
+/**
+ * Used for setting or getting function definitions.
+ * The `@parameters` field holds the parameter type information, and the `@body` field holds the function body,
+ * which can be either a context (for multi-line functions) or an expression (for single-line functions).
+ *
+ * - If function has no parameters, empty object must be set or will be returned
+ * - Function must have a body
+ * - In `@parameters`, a `null` value denotes an untyped (unannotated) parameter
+ *
+ * To get function definition, use:
+ *  - `service.get("calculateLoanOffer.*")`
+ *  - `service.get("calculateLoanOffer", "FUNCTION_DEFINITIONS")` -> returns `calculateLoanOffer` definition
+ *  - `service.get("*", "FUNCTION_DEFINITIONS")` -> returns all function definitions in the root context
+ */
+export interface PortableFunctionDefinition extends PortableObject {
+    '@kind': 'function';
+    '@parameters': Record<string, PortableTypeReference | PortableTypedValue | null>;
+    '@body': PortableContext | PortableExpression;
+}
+/**
+ * Use only for getting function schemas, usage:
+ *  - `service.get("calculateLoanOffer")` -> returns `calculateLoanOffer` schema
+ *  - `service.get("*")` -> returns all function schemas in the context, because default filter is "CONTEXT"
+ */
+export interface PortableFunctionSchema extends PortableObject {
+    '@kind': 'function-schema';
+    '@parameters': Record<string, PortableTypeReference | PortableTypedValue | null>;
+    '@return': PortableTypeReference | PortableTypedValue;
+}
+/**
+ * Used for setting or getting function invocation definitions.
+ * - `@method` holds the function name, can also hold decision table hit-policy keywords (`firstMatch`, `uniqueMatch`, ...).
+ * - `@arguments` holds the argument values; if the call takes no arguments, an empty array must be set.
+ * `@arguments` can also hold a decision table definition (a `PortableContext` with `inputs`, `rules`, and optional `default`).
+ *
+ * `@type` is available only in return object, it is linked type information for the invocation result, inferred by the engine and provided
+ * for the host's convenience.
+ */
+export interface PortableInvocationDefinition extends PortableObject {
+    '@kind': 'invocation';
+    '@type'?: PortableTypeReference;
+    '@method': string;
+    '@arguments': PortableValue[];
+}
+/** Machine-readable discriminant of a `PortableError`. */
+export type PortableErrorType = 
+/** A path segment does not resolve to any entry. */
+'EntryNotFound'
+/** Invalid/empty path, type mismatch (e.g. indexing a record), out-of-bounds, or negative index. */
+ | 'WrongFieldPath'
+/** A rename/insert collides with a name already present in the same context. */
+ | 'DuplicateName'
+/** A mutation produced an incompatible type or broke an existing reference. */
+ | 'Linking'
+/** An expression string or Portable payload failed to parse. */
+ | 'Parse'
+/** Evaluation failed while executing the model (e.g. a runtime/type error). */
+ | 'Execution';
+/** Where an error occurred inside EdgeRules DSL source, when the engine can pinpoint it. */
+export interface PortableSourceLocation {
+    /** 1-based line within the offending expression/source. */
+    line?: number;
+    /** 1-based column within the offending expression/source. */
+    column?: number;
+    /** The offending expression, echoed back for display. */
+    expression?: PortableExpressionString;
+}
+/**
+ * A structured error returned or thrown across the host boundary.
+ * Discriminated by `type`; safe to surface `message` directly to the user.
+ */
+export interface PortableError {
+    '@kind': 'error';
+    /** The discriminant a GUI switches on. */
+    type: PortableErrorType;
+    /** Human-readable description of what went wrong. */
+    message: string;
+    /** Model path the operation targeted, when path-based (CRUD ops, `execute` method). */
+    path?: string;
+    /**
+     * Secondary path for relational errors:
+     *   - `DuplicateName`: the path of the existing entry it collided with.
+     *   - `WrongFieldPath` on rename: the rejected target path.
+     */
+    conflictPath?: string;
+    /** Source location for `Parse`, `Linking`, and `Execution` errors. */
+    location?: PortableSourceLocation;
+}

package/dist/portable.js

@@ -0,0 +1,19 @@
+/**
+ * Portable JSON format for EdgeRules.
+ *
+ * This file ships with EdgeRules and is the TypeScript contract a host / GUI uses to:
+ *   1. read the model using:
+ *      - `service.get(path, filter?): PortableNode | PortableError`
+ *      - `service.get("*", filter?): PortableRootContext | PortableError`
+ *   2. set new entities to the model using:
+ *      - `service.set(path, PortableNode): PortableNode | PortableError`
+ *
+ * Filters select which view of an entry is returned:
+ *  - "CONTEXT" (default) — runtime/data view: contexts, values, expressions, and function *schemas*.
+ *  - "TYPE_DEFINITIONS" — type definitions only.
+ *  - "FUNCTION_DEFINITIONS" — function definitions (parameters + body) only.
+ *  - "ALL" — every view combined (context, type, and function definitions).
+ *
+ * On success the returned node is enriched with linked type information; otherwise a PortableError is returned.
+ */
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@edgerules/portable",
+  "version": "0.0.0-alpha.202607041229",
+  "type": "module",
+  "description": "Portable JSON type definitions for EdgeRules.",
+  "exports": {
+    ".": {
+      "types": "./dist/portable.d.ts",
+      "import": "./dist/portable.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}