@codenotch/process 0.0.0-dev

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

@@ -0,0 +1,17 @@
+import type { Json, Template, TemplateKind } from '../lib/types';
+import type { EmailTemplatePayload, PdfPageOptions, PdfTemplatePayload } from '../lib/renderings';
+export type { EmailTemplatePayload, PdfPageOptions, PdfTemplatePayload, Template, TemplateKind, };
+type MaybePromise<T> = T | PromiseLike<T>;
+export declare const template: Readonly<{
+    /** Declares an email template: render(data) returns { subject, html, text? }. */
+    email: <D = Json>(render: (data: D) => MaybePromise<EmailTemplatePayload>) => Template<D, "email">;
+    /**
+     * Declares a pdf template: render(data) returns { html } (print CSS; Chromium paged
+     * media — @page margin boxes, counter(page/pages) — works natively). The optional
+     * first argument sets the page: template.pdf({ format: 'A4' }, render).
+     */
+    pdf: {
+        <D = Json>(render: (data: D) => MaybePromise<PdfTemplatePayload>): Template<D, "pdf">;
+        <D = Json>(page: PdfPageOptions, render: (data: D) => MaybePromise<PdfTemplatePayload>): Template<D, "pdf">;
+    };
+}>;

package/dist/types/testing/api.d.ts

@@ -0,0 +1,175 @@
+import type { Activity, DurationLike, DurationParts, Json, Serializable } from '../lib/types';
+/** The body of one test. It receives the environment; throwing fails the test. */
+export type TestFn = (env: TestEnv) => void | PromiseLike<void>;
+export interface TestOptions {
+    /** Per-test budget in milliseconds. Default: two minutes. */
+    timeout?: number;
+}
+/** The simulated caller of env.start — reaches the process as ctx.user. */
+export interface TestUser {
+    /** Any stable string; generated when omitted. */
+    id?: string;
+    email?: string;
+    name?: string;
+    roles?: string[];
+    /** Defaults to 'internal'. The process's declared auth is enforced against it. */
+    group?: 'internal' | 'external';
+    language?: string;
+}
+export interface StartOptions {
+    input?: Serializable;
+    /** Omitted: the process starts as the system user. */
+    user?: TestUser;
+    /** Overrides applied on top of the project's resolved parameters. */
+    params?: Record<string, Serializable>;
+}
+/** Where an instance stands. Terminal: SUCCESS, ERROR, STOPPED, TERMINATED, FAILED_RECOVERY. */
+export type RunState = 'SUCCESS' | 'ERROR' | 'WAITING' | 'EXECUTING' | 'READY' | 'IDLE' | 'PAUSED' | 'STOPPED' | 'STOPPING' | 'TERMINATED' | 'FAILED_RECOVERY';
+/** The failure of an ERROR run, as journaled. */
+export interface RunFailure {
+    name: string;
+    message: string;
+    /** The code of a ProcessError; null/absent otherwise. */
+    code?: string | null;
+    details?: Json;
+}
+/** What an api-triggered process answered with. */
+export interface RunResponse {
+    status: number;
+    body?: Json;
+    headers?: Record<string, string> | null;
+}
+/** One signal a run sent: its ref and its payload. */
+export interface SentSignal {
+    ref: string;
+    data: Json;
+}
+/** Handle on a process instance the test started. */
+export interface TestRun<Out = Json> {
+    readonly instanceId: string;
+    /** 'SUCCESS', 'ERROR', 'WAITING', … Reading is safe in any state. */
+    state(): Promise<RunState>;
+    /** What the process returned; reading it from a failed run throws that failure. */
+    output(): Promise<Out>;
+    /** The failure of an ERROR run; reading it from a run that did not fail throws. */
+    failure(): Promise<RunFailure>;
+    /** What it answered with — how a test tells a 403 from a 200. Null when it never responded. */
+    response(): Promise<RunResponse | null>;
+    /** The arguments of each call of that step, in order. Takes the imported activity handle or a name. */
+    activityCalls<In>(activity: Activity<In, unknown>): Promise<In[]>;
+    activityCalls(activity: string): Promise<Json[]>;
+    /** The signals it sent; a trailing '*' matches by prefix ('contact.*'). */
+    sentSignals(pattern?: string): Promise<SentSignal[]>;
+    /** The payloads of the declared events it sent to its caller (every event when no id is given). */
+    sentEvents(eventId?: string): Promise<Json[]>;
+}
+/** Handle on one datastore of the deployed project. */
+export interface TestStore<Row = Record<string, Json>> {
+    /** Empties this store and inserts the rows (each may carry its Id). Nothing else is touched. */
+    seed(rows: ReadonlyArray<Partial<Row> & {
+        Id?: string;
+    }>): Promise<void>;
+    /** Every row, as stored. */
+    rows(): Promise<Row[]>;
+    /** One record by id, or null. */
+    get(id: string): Promise<Row | null>;
+}
+/**
+ * A duration for env.advance: everything a DurationLike accepts ('PT5M', 180000,
+ * { days: 3 }), plus the ms shorthand ({ ms: 500 }). Calendar components
+ * (years/months) have no fixed length and are rejected, as ctx.wait rejects them.
+ */
+export type AdvanceDuration = DurationLike | (DurationParts & {
+    ms?: number;
+});
+export interface TestActivityOptions {
+    /** Per-call budget; unbounded when absent (the test's own budget still applies). */
+    timeout?: DurationLike;
+}
+/** The environment a test drives: seed data, install mocks, start processes, move the clock, assert. */
+export interface TestEnv {
+    /** Handle on one of the project's tables. */
+    table<Row = Record<string, Json>>(name: string): TestStore<Row>;
+    /** Handle on one of the project's document stores. */
+    doc<Doc = Record<string, Json>>(store: string): TestStore<Doc>;
+    /**
+     * Replaces a step for this test. Pass the imported activity handle for a typed
+     * mock, or name a built-in step by its activity name ('table.write', 'node.run',
+     * 'http.fetch', 'email.send', …) / a project activity by its export. The mock
+     * receives the arguments the process passed; throwing fails the step exactly
+     * like a real failure.
+     */
+    mock<In, Out>(activity: Activity<In, Out>, fn: (args: In) => Out | PromiseLike<Out>): void;
+    mock(activity: string, fn: (args: any) => Serializable | PromiseLike<Serializable>): void;
+    /** Stubs the one CNQL query matching this ref; every other query still runs for real. */
+    onQuery(queryRef: string, fn: (args: Record<string, Json> | null) => Serializable | PromiseLike<Serializable>): void;
+    /**
+     * Executes one of the project's DEPLOYED activities as a black box — the test-side
+     * mirror of ctx.activity. The real artifact runs on the real Node runtime with a
+     * real io; mocks do not apply (a mock replaces a step inside a process run — this
+     * IS the activity), and it is a single attempt: retries are a calling process's
+     * policy, not the activity's behavior. A failure throws exactly what a process
+     * would catch (ProcessError for coded failures).
+     */
+    activity<In, Out>(activity: Activity<In, Out>, input: In, opts?: TestActivityOptions): Promise<Out>;
+    activity<T = Json>(reference: string, input?: Serializable, opts?: TestActivityOptions): Promise<T>;
+    /** Starts a process and settles the world: when this resolves, the run parked or finished. */
+    start<Out = Json>(processId: string, options?: StartOptions): Promise<TestRun<Out>>;
+    /** Moves the test's clock and runs everything that came due. */
+    advance(duration: AdvanceDuration): Promise<void>;
+    /** Emits a signal, exactly as a process would. */
+    sendSignal(ref: string, data?: Serializable): Promise<void>;
+    /** The test's current time, ISO-8601 UTC. It moves only when the test advances it. */
+    now(): string;
+}
+/** The assertion vocabulary. All object matching compares numbers by value and dates normalized to UTC. */
+export interface Matchers {
+    /** The value matches exactly, with no extra fields anywhere. */
+    toEqual(expected: unknown): void;
+    /** Every field the subset lists matches; unlisted fields are ignored (recursively). */
+    toMatch(subset: unknown): void;
+    /** Some element of the array matches the subset. */
+    toContainMatch(subset: unknown): void;
+    toHaveLength(n: number): void;
+    /** Scalar equality. */
+    toBe(expected: unknown): void;
+    toBeNull(): void;
+    toBeDefined(): void;
+    toBeUndefined(): void;
+}
+/** Declares one test. Files declare with `test(...)`; the platform runs them in declaration order. */
+export declare function test(name: string, fn: TestFn): void;
+export declare function test(name: string, options: TestOptions, fn: TestFn): void;
+/** Wraps a value for assertion. A failed expectation throws with the path it differed at. */
+export declare const expect: (actual: unknown) => Matchers;
+/**
+ * The platform surface behind env (ScriptTestEnvironment on the C# side). The names
+ * and signatures here are the stable contract between the engine and this bundle.
+ * Task-returning members surface as promises in the test host.
+ */
+export interface TestHostBridge {
+    Seed(datastore: string, isDocument: boolean, rowsJson: string | null): PromiseLike<void>;
+    Rows(datastore: string, isDocument: boolean): PromiseLike<string | null>;
+    Get(datastore: string, isDocument: boolean, id: string): PromiseLike<string | null>;
+    /** Routes the named step to this engine's __invokeMock while the test runs. */
+    Mock(activityName: string): void;
+    Now(): string;
+    /** Returns the outcome envelope: {ok:true, result} or {ok:false, error:{name,code,message}}. */
+    Activity(reference: string, inputJson: string | null, timeoutMsJson: string | null): PromiseLike<string>;
+    Start(processId: string, optionsJson: string | null): PromiseLike<string>;
+    Advance(durationJson: string | null): PromiseLike<void>;
+    SendSignal(signalRef: string, dataJson: string | null): PromiseLike<void>;
+    RunState(instanceId: string): PromiseLike<string>;
+    RunOutput(instanceId: string): PromiseLike<string | null>;
+    RunFailure(instanceId: string): PromiseLike<string | null>;
+    RunResponse(instanceId: string): PromiseLike<string | null>;
+    RunActivityCalls(instanceId: string, activityName: string): PromiseLike<string | null>;
+    RunSentSignals(instanceId: string, refPattern: string | null): PromiseLike<string | null>;
+    RunSentEvents(instanceId: string, eventId: string | null): PromiseLike<string | null>;
+}
+/** @internal The declared tests, for the runner: name + timeout, in declaration order. */
+export declare const testNamesJson: () => string;
+/** @internal Runs one declared test against the host bridge the runner passes. */
+export declare const runTest: (index: number, host: TestHostBridge) => Promise<void>;
+/** @internal Invokes the mock the running test installed for an activity. */
+export declare const invokeMock: (activityName: string, inputJson: string | null) => Promise<string | null>;

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

@@ -0,0 +1,2 @@
+export { test, expect } from './api';
+export type { AdvanceDuration, Matchers, RunFailure, RunResponse, RunState, SentSignal, StartOptions, TestActivityOptions, TestEnv, TestFn, TestOptions, TestRun, TestStore, TestUser, } from './api';

package/dist/types/testing/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/testing/stdlib.d.ts

@@ -0,0 +1,79 @@
+import * as lib from '../lib/index';
+/**
+ * The crypto backing ScriptTestHost injects as __host — the same pure functions the
+ * workflow runtime provides, so hash.* behaves identically in tests and processes.
+ */
+export interface TestCryptoHost {
+    HashSha256(dataBase64: string): string;
+    HashHmacSha256(keyBase64: string, dataBase64: string): string;
+    TimingSafeEqual(aBase64: string, bBase64: string): boolean;
+}
+/**
+ * Binds the library's engine seam to what the test host actually provides: the pure
+ * crypto backing. Everything else on the seam belongs to a running instance and is
+ * unreachable through the public surface — reaching it anyway names the gap.
+ */
+export declare const installTestBindings: (host: TestCryptoHost | undefined) => void;
+/**
+ * What require('@codenotch/process') returns in the test host: the real library, with
+ * the process-definition constructs replaced by refusals that say what to do instead.
+ */
+export declare const stdlibModule: Readonly<{
+    process: () => never;
+    api: Readonly<{
+        get: () => never;
+        post: () => never;
+        put: () => never;
+        delete: () => never;
+    }>;
+    signal: () => never;
+    timer: () => never;
+    connectorEvent: () => never;
+    install: () => never;
+    manual: () => never;
+    events: () => never;
+    ProcessError: typeof lib.ProcessError;
+    CallFailedError: typeof lib.CallFailedError;
+    TimeoutError: typeof lib.TimeoutError;
+    CancelledError: typeof lib.CancelledError;
+    CallCompletedError: typeof lib.CallCompletedError;
+    NotFoundError: typeof lib.NotFoundError;
+    Instant: typeof lib.Instant;
+    Duration: typeof lib.Duration;
+    Decimal: typeof lib.Decimal;
+    base64: {
+        encode(data: string | Uint8Array, options?: {
+            url?: boolean;
+        }): string;
+        decode(text: string): Uint8Array;
+        decodeToText(text: string): string;
+    };
+    hex: {
+        encode(data: string | Uint8Array): string;
+        decode(text: string): Uint8Array;
+        decodeToText(text: string): string;
+    };
+    utf8: {
+        encode(text: string): Uint8Array;
+        decode(bytes: Uint8Array): string;
+    };
+    url: typeof lib.url;
+    canonicalJson: (value: lib.Serializable) => string;
+    chunk: <T>(items: readonly T[], size: number) => T[][];
+    uniqueBy: <T>(items: readonly T[], key: (item: T) => unknown) => T[];
+    is: {
+        email: (value: unknown) => boolean;
+        uuid: (value: unknown) => boolean;
+        url: (value: unknown) => boolean;
+        isoDate: (value: unknown) => boolean;
+        isoDateTime: (value: unknown) => boolean;
+        isoDuration: (value: unknown) => boolean;
+        ipv4: (value: unknown) => boolean;
+        ipv6: (value: unknown) => boolean;
+    };
+    hash: {
+        sha256(data: string | Uint8Array, output?: lib.HashOutput): string;
+        hmacSha256(key: string | Uint8Array, data: string | Uint8Array, output?: lib.HashOutput): string;
+        timingSafeEqual(a: string | Uint8Array, b: string | Uint8Array): boolean;
+    };
+}>;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@codenotch/process",
+  "version": "0.0.0-dev",
+  "description": "Types and standard library for Codenotch script processes. Processes execute on the server only: the engine embeds the compiled runtime (dist/prelude.js); this package distributes the type declarations.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EchinoHub/service-core.git",
+    "directory": "src/codenotch-process"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/types/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/lib/index.d.ts"
+    },
+    "./activity": {
+      "types": "./dist/types/activity/index.d.ts",
+      "default": "./dist/activity.mjs"
+    },
+    "./template": {
+      "types": "./dist/types/template/index.d.ts",
+      "default": "./dist/template.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/testing/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/types",
+    "dist/activity.mjs",
+    "dist/template.mjs"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.9",
+    "typescript": "^5.9.2"
+  }
+}