@jarenjs/play 0.34.2 → 0.43.1

package/README.md

@@ -3,8 +3,8 @@
 **A JSON-engine playground — understand an engine before you compose it.**
 
 Pick an engine (JSONPath, JSON Pointer, JSON Patch, `$query`, JSLT,
-markdown, mermaid, …), feed it a source input and one or more datasets from
-a curated example library, and watch it run. Where `@jarenjs/studio` is for
+markdown, mermaid, a `$contract` document, …), feed it a source input and
+one or more datasets from a curated example library, and watch it run. Where `@jarenjs/studio` is for
 building an application out of many files, `@jarenjs/play` is for
 learning one engine standalone — a reference bench you experiment on first.
 

package/dist/types/component/index.d.ts

@@ -72,7 +72,7 @@ export declare function createPlayComponent(options?: {
     engines: Readonly<Record<string, import("../index.js").EngineDescriptor>>;
     examples: readonly import("../index.js").PlayExample[];
     engineIds: typeof engineIds;
-    runExample: (engineId: any, source: any, data: any, perCall?: {}) => import("../index.js").PlayResult;
+    runExample: (engineId: any, source: any, data: any, perCall?: {}) => import("../index.js").PlayResult | Promise<import("../index.js").PlayResult>;
     operators: {
         toOptions: () => any;
     } | undefined;

package/dist/types/index.d.ts

@@ -154,7 +154,13 @@ export type EngineDescriptor = {
      * - live mode selects (may be absent)
      */
     optionPanes?: OptionPane[];
-    run: (source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult;
+    /**
+     *   most engines answer synchronously; an engine whose run resolves real
+     *   promises (the contract engine's dispatch panel) answers a thenable
+     *   Result, which `runExample` passes through with the same never-throw
+     *   contract (a rejection settles into an error Result)
+     */
+    run: (source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult | Promise<PlayResult>;
 };
 export type RunOptions = {
     /**
@@ -289,7 +295,11 @@ export type PlayExample = {
  * @property {EnginePane[]} sourcePanes - the engine INPUT pane(s)
  * @property {EnginePane[]} dataPanes - the JSON it runs against (may be [])
  * @property {OptionPane[]} [optionPanes] - live mode selects (may be absent)
- * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult} run
+ * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult | Promise<PlayResult>} run
+ *   most engines answer synchronously; an engine whose run resolves real
+ *   promises (the contract engine's dispatch panel) answers a thenable
+ *   Result, which `runExample` passes through with the same never-throw
+ *   contract (a rejection settles into an error Result)
  */
 /**
  * @typedef {Object} RunOptions
@@ -328,12 +338,15 @@ export declare function engineIds(): string[];
 export declare const EXAMPLES: readonly PlayExample[];
 /**
  * Run one engine over a source + data. An unknown engine (or a throwing
- * runner) yields an error Result — this never throws.
+ * runner) yields an error Result — this never throws. A synchronous
+ * engine answers a Result; an async engine (the contract dispatch)
+ * answers a Promise of one that never rejects — a host that must know
+ * which awaits `Promise.resolve(runExample(…))`.
  * @param {string} engineId
  * @param {Record<string, string>} source
  * @param {Record<string, string>} data
  * @param {RunOptions} [options] - operators (query/jslt), the option-pane
  *   config, and host renderers (markdown/mermaid/charts)
- * @returns {PlayResult}
+ * @returns {PlayResult | Promise<PlayResult>}
  */
-export declare function runExample(engineId: string, source: Record<string, string>, data: Record<string, string>, options?: RunOptions): PlayResult;
+export declare function runExample(engineId: string, source: Record<string, string>, data: Record<string, string>, options?: RunOptions): PlayResult | Promise<PlayResult>;

package/docs/PLAY-FORMAT.md

@@ -13,7 +13,7 @@ EngineDescriptor = {
   lead?:       string,        // one line describing the engine
   sourcePanes: EnginePane[],  // the engine INPUT (usually one)
   dataPanes:   EnginePane[],  // the JSON it runs against (may be empty)
-  run:         (source, data) => PlayResult,
+  run:         (source, data) => PlayResult | Promise<PlayResult>,
 }
 EnginePane = { key: string, label: string, control?: 'code' | 'text' }
 ```
@@ -27,6 +27,13 @@ EnginePane = { key: string, label: string, control?: 'code' | 'text' }
 - `run(source, data)` is PURE and NEVER throws: it wraps the real shipped
   compiler and returns a `PlayResult`. `source` / `data` are maps keyed
   by the pane `key`s, holding the raw text.
+- Most engines answer synchronously. An engine whose run resolves real
+  promises (the contract engine's dispatch panel invokes a local client)
+  answers a **thenable** `PlayResult`; `runExample` passes it through
+  under the same never-throw contract — a rejection settles into an
+  error Result, so `await Promise.resolve(runExample(…))` is total for
+  every engine. A host that renders live must drop a settled result an
+  even newer run superseded (the website keys runs by a sequence).
 
 ## §2 The result
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/play",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -56,9 +56,10 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.2",
-    "@jarenjs/josl": "^0.34.2",
-    "@jarenjs/json": "^0.34.2",
-    "@jarenjs/validate": "^0.34.2"
+    "@jarenjs/contract": "^0.43.1",
+    "@jarenjs/core": "^0.43.1",
+    "@jarenjs/josl": "^0.43.1",
+    "@jarenjs/json": "^0.43.1",
+    "@jarenjs/validate": "^0.43.1"
   }
 }

package/src/engines.js

@@ -18,6 +18,9 @@ import { parseXQuery } from '@jarenjs/json/xquery';
 import { parseJosl, stringifyJosl, stringifyJsonx } from '@jarenjs/josl';
 import { parseCsvDocument, stringifyCsv, sniffCsvDialect } from '@jarenjs/josl/csv';
 import { createTypeTestCompiler } from '@jarenjs/validate/query';
+import { compileContract } from '@jarenjs/contract';
+import { openLocalClient } from '@jarenjs/contract/local';
+import { toOpenApi, toTypeScript } from '@jarenjs/contract/project';
 import { formatMs } from './format.js';
 
 const compileTypeTest = createTypeTestCompiler();
@@ -555,6 +558,74 @@ export const ENGINE_LIST = [
       return okPanels(renderedPanels(view), ...renderTiming(view, t1 - t0));
     },
   },
+  {
+    // the one ASYNC engine: the dispatch panel resolves a real client
+    // outcome, so run() returns a Promise — runExample and the hosts
+    // pass a thenable Result through (PLAY-FORMAT §2)
+    id: 'contract', label: 'Contract', lead: 'A $contract document — operations two ends may exchange, compiled, projected and dispatched in-process.',
+    sourcePanes: [{ key: 'document', label: '$contract document', control: 'code' }],
+    dataPanes: [{ key: 'call', label: 'Dispatch — { "op", "input" }' }],
+    async run(source, data) {
+      const d = parseJson(source.document, 'document'); if (d.error) return failParse(d);
+      let contract; const t0 = now();
+      // a compile refusal is the engine's lesson: a stable JC00xx code
+      // with the JSON Pointer of the member at fault
+      try { contract = compileContract(d.value); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'document')); }
+      const t1 = now();
+      let openapi, types;
+      try {
+        openapi = toOpenApi(contract, {
+          info: {
+            title: typeof d.value?.id === 'string' ? d.value.id : 'contract',
+            version: typeof d.value?.version === 'string' ? d.value.version : '0',
+          },
+        });
+        types = toTypeScript(contract);
+      }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'document')); }
+      // the dispatch pane: an op + input run against trivial echo
+      // handlers over the local binding — the whole pipeline with no
+      // network. Output validation is DECLARED off (a capability the
+      // binding states), so any echo crosses; input validation still
+      // refuses a bad input with its outcome, which is the lesson.
+      /** @type {import('./index.js').Panel} */
+      let dispatch = {
+        id: 'dispatch', label: 'Dispatch', kind: 'note', tone: 'info',
+        text: 'Type { "op": "<operation id>", "input": { … } } in the Dispatch pane to run an operation against echo handlers (validateOutput declared \'never\').',
+      };
+      if (String(data.call ?? '').trim() !== '') {
+        const call = parseJson(data.call, 'call'); if (call.error) return failParse(call);
+        const op = call.value !== null && typeof call.value === 'object' ? call.value.op : undefined;
+        if (typeof op !== 'string') {
+          dispatch = { id: 'dispatch', label: 'Dispatch', kind: 'note', tone: 'warn', text: 'the call must be an object naming an "op" (and optionally an "input")' };
+        }
+        else {
+          /** @type {Record<string, (input: any) => any>} */
+          const handlers = {};
+          for (const id of Object.keys(contract.operations)) handlers[id] = (input) => input;
+          const client = openLocalClient(contract, handlers, { validateOutput: 'never' });
+          try {
+            const outcome = await client.invoke(op, call.value.input ?? {});
+            dispatch = { id: 'dispatch', label: 'Dispatch (echo)', kind: 'code', text: fmt(outcome) };
+          }
+          catch (err) {
+            // a host mistake (JC1005: unknown, opaque or subscribe
+            // operation) is the panel's answer, not an engine failure
+            dispatch = { id: 'dispatch', label: 'Dispatch', kind: 'note', tone: 'warn', text: msg(err) };
+          }
+          finally { client.close(); }
+        }
+      }
+      const t2 = now();
+      return okPanels([
+        { id: 'describe', label: 'describe()', kind: 'code', text: fmt(contract.describe()) },
+        { id: 'openapi', label: 'OpenAPI', kind: 'code', text: fmt(openapi.document) },
+        { id: 'types', label: 'TypeScript', kind: 'code', text: types },
+        dispatch,
+      ], t1 - t0, t2 - t1);
+    },
+  },
   // ——— the visual engines: descriptor + examples here, rendering delegated ———
   visual('markdown', 'Markdown', 'CommonMark + GFM + frontmatter → a JSON AST, rendered live.', { sourceLabel: 'Markdown' }),
   visual('mermaid', 'Mermaid', 'Diagrams-as-code → a geometry-free AST → pure-vnode SVG.', { sourceLabel: 'Mermaid' }),

package/src/examples.js

@@ -543,4 +543,46 @@ is a fixed point.
       name: { type: 'string', minLength: 2 }, email: { type: 'string', format: 'email' }, age: { type: 'integer', minimum: 13 },
     }, required: ['name', 'email'] }) },
     datasets: [{ label: 'invalid', data: { data: j({ name: 'A', email: 'not-an-email', age: 7 }) } }] },
+
+  // ——— Contract ($contract document → describe / OpenAPI / TypeScript / dispatch) ———
+  { id: 'contract-shop', label: 'A shop contract', engine: 'contract',
+    source: { document: j({ $contract: '0.1', id: 'shop', version: '1',
+      $defs: { Product: { type: 'object', required: ['id', 'name', 'price'], properties: {
+        id: { type: 'integer' }, name: { type: 'string', minLength: 1 }, price: { type: 'number', minimum: 0 } } } },
+      operations: {
+        'catalog.load': { kind: 'read',
+          input: { type: 'object', properties: { since: { type: 'string', format: 'date-time' } } },
+          output: { type: 'array', items: { $ref: '#/$defs/Product' } },
+          http: { method: 'GET', path: '/api/catalog' },
+          doc: 'The whole catalog.' },
+        'product.save': { kind: 'command',
+          input: { type: 'object', required: ['id', 'product'], properties: {
+            id: { type: 'integer' }, product: { $ref: '#/$defs/Product' } } },
+          output: { $ref: '#/$defs/Product' },
+          errors: { conflict: { status: 409 } },
+          policy: { idempotency: 'optional' },
+          http: { method: 'PUT', path: '/api/products/{id}' } },
+      } }) },
+    datasets: [
+      { label: 'a valid save', data: { call: j({ op: 'product.save', input: { id: 7, product: { id: 7, name: 'Duck', price: 9.99 } } }) } },
+      { label: 'an invalid input', data: { call: j({ op: 'product.save', input: { id: 'seven' } }) } },
+      { label: 'no dispatch', data: { call: '' } },
+    ] },
+  { id: 'contract-minimal', label: 'One operation, no http', engine: 'contract',
+    source: { document: j({ $contract: '0.1', id: 'echo', operations: {
+      'echo.say': { kind: 'command',
+        input: { type: 'object', required: ['text'], properties: { text: { type: 'string' } } },
+        output: true,
+        doc: 'No http member: the binding defaults to POST /echo.say.' },
+    } }) },
+    datasets: [{ label: 'say something', data: { call: j({ op: 'echo.say', input: { text: 'hello' } }) } }] },
+  { id: 'contract-broken', label: 'A refusal, with its docPath', engine: 'contract',
+    source: { document: j({ $contract: '0.1', id: 'broken', operations: {
+      'catalog.load': { kind: 'read',
+        input: { type: 'object', properties: { since: { type: 'string' } } },
+        // no output member: JC00xx at compile, never at request time —
+        // the error names /operations/catalog.load with its code
+        http: { method: 'GET', path: '/api/catalog' } },
+    } }) },
+    datasets: [{ label: 'nothing to dispatch', data: { call: '' } }] },
 ];

package/src/index.js

@@ -98,7 +98,11 @@ import { EXAMPLE_LIST } from './examples.js';
  * @property {EnginePane[]} sourcePanes - the engine INPUT pane(s)
  * @property {EnginePane[]} dataPanes - the JSON it runs against (may be [])
  * @property {OptionPane[]} [optionPanes] - live mode selects (may be absent)
- * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult} run
+ * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult | Promise<PlayResult>} run
+ *   most engines answer synchronously; an engine whose run resolves real
+ *   promises (the contract engine's dispatch panel) answers a thenable
+ *   Result, which `runExample` passes through with the same never-throw
+ *   contract (a rejection settles into an error Result)
  */
 
 /**
@@ -162,23 +166,31 @@ function withConfig(engine, options) {
 
 /**
  * Run one engine over a source + data. An unknown engine (or a throwing
- * runner) yields an error Result — this never throws.
+ * runner) yields an error Result — this never throws. A synchronous
+ * engine answers a Result; an async engine (the contract dispatch)
+ * answers a Promise of one that never rejects — a host that must know
+ * which awaits `Promise.resolve(runExample(…))`.
  * @param {string} engineId
  * @param {Record<string, string>} source
  * @param {Record<string, string>} data
  * @param {RunOptions} [options] - operators (query/jslt), the option-pane
  *   config, and host renderers (markdown/mermaid/charts)
- * @returns {PlayResult}
+ * @returns {PlayResult | Promise<PlayResult>}
  */
 export function runExample(engineId, source, data, options = {}) {
   const engine = ENGINES[engineId];
   if (engine === undefined) {
     return { ok: false, timing: null, error: { message: `unknown engine: ${engineId}` }, panels: [] };
   }
+  const failed = (/** @type {unknown} */ err) =>
+    /** @type {PlayResult} */ ({ ok: false, timing: null, error: { message: String(/** @type {any} */ (err)?.message ?? err) }, panels: [] });
   try {
-    return engine.run(source ?? {}, data ?? {}, withConfig(engine, options));
+    const result = engine.run(source ?? {}, data ?? {}, withConfig(engine, options));
+    return result !== null && typeof result === 'object' && typeof (/** @type {any} */ (result).then) === 'function'
+      ? /** @type {Promise<PlayResult>} */ (result).then((r) => r, failed)
+      : result;
   }
   catch (err) {
-    return { ok: false, timing: null, error: { message: String(/** @type {any} */ (err)?.message ?? err) }, panels: [] };
+    return failed(err);
   }
 }