@telorun/assert 0.3.1 → 0.5.1

package/README.md

@@ -1,6 +1,21 @@
-# ⚡ Telo
-
-Runtime for declarative backends.
+<p align="center">
+  <img src="./assets/telo.png" alt="Telo" width="200" />
+</p>
+
+<h1 align="center">Telo</h1>
+
+<p align="center">Runtime for declarative backends.</p>
+
+<p align="center">
+  <a href="https://github.com/telorun/telo/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/telorun/telo/actions/workflows/test.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@telorun/cli"><img alt="node" src="https://img.shields.io/node/v/@telorun/cli" /></a>
+  <br />
+  <a href="https://github.com/telorun/telo/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/issues"><img alt="Issues" src="https://img.shields.io/github/issues/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/pulls"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr/telorun/telo" /></a>
+  <br />
+  <img alt="Changesets" src="https://img.shields.io/badge/maintained%20with-changesets-176de3" />
+</p>
 
 Telo is an execution engine (Micro-Kernel) that runs logic defined entirely in YAML manifests. Instead of writing imperative backend code, you define your routes, databases, schemas, and AI workflows as atomic, interconnected YAML documents. Telo takes those manifests and runs them.
 

package/dist/colors.d.ts

@@ -0,0 +1,12 @@
+import type { ResourceContext } from "@telorun/sdk";
+/**
+ * Build the small ANSI color helpers used by every assert kind. Returns
+ * pass-through (uncolored) helpers when stderr isn't a TTY so piped /
+ * redirected output stays clean.
+ */
+export declare function createColors(ctx: ResourceContext): {
+    bold: (t: string) => string;
+    red: (t: string) => string;
+    green: (t: string) => string;
+    dim: (t: string) => string;
+};

package/dist/colors.js

@@ -0,0 +1,15 @@
+/**
+ * Build the small ANSI color helpers used by every assert kind. Returns
+ * pass-through (uncolored) helpers when stderr isn't a TTY so piped /
+ * redirected output stays clean.
+ */
+export function createColors(ctx) {
+    const useColor = ctx.stderr.isTTY ?? false;
+    const c = (code, text) => useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+    return {
+        bold: (t) => c("1", t),
+        red: (t) => c("31", t),
+        green: (t) => c("32", t),
+        dim: (t) => c("2", t),
+    };
+}

package/dist/contains.d.ts

@@ -0,0 +1,16 @@
+import { ResourceContext } from "@telorun/sdk";
+import { Static } from "@sinclair/typebox";
+export declare const schema: import("@sinclair/typebox").TObject<{
+    metadata: import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+    }>;
+}>;
+type AssertManifest = Static<typeof schema>;
+interface ContainsInput {
+    actual: unknown;
+    value: unknown;
+}
+export declare function create(manifest: AssertManifest, ctx: ResourceContext): Promise<{
+    invoke: (input: ContainsInput) => boolean;
+}>;
+export {};

package/dist/contains.js

@@ -0,0 +1,53 @@
+import { InvokeError } from "@telorun/sdk";
+import { Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+import { deepEquals } from "./deep-equals.js";
+export const schema = Type.Object({
+    metadata: Type.Object({
+        name: Type.String(),
+    }),
+});
+export async function create(manifest, ctx) {
+    const { bold, red, green, dim } = createColors(ctx);
+    const name = manifest.metadata.name;
+    return {
+        invoke: (input) => {
+            const { actual, value } = input ?? {};
+            let ok = false;
+            let kind = "";
+            if (typeof actual === "string") {
+                if (typeof value !== "string") {
+                    const message = `actual is a string but value is ${typeof value}; expected substring`;
+                    ctx.stderr.write(bold(red(`Assert.Contains.${name}: assertion failed`)) +
+                        "\n" +
+                        `  ${red("✗")} ${message}\n`);
+                    throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Contains "${name}": ${message}`);
+                }
+                kind = "substring";
+                ok = actual.includes(value);
+            }
+            else if (Array.isArray(actual)) {
+                kind = "element";
+                ok = actual.some((item) => deepEquals(item, value));
+            }
+            else {
+                const message = `actual must be string or array; got ${typeof actual}`;
+                ctx.stderr.write(bold(red(`Assert.Contains.${name}: assertion failed`)) +
+                    "\n" +
+                    `  ${red("✗")} ${message}\n`);
+                throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Contains "${name}": ${message}`);
+            }
+            if (ok) {
+                ctx.stdout.write(bold(green(`Assert.Contains.${name}: assertion passed`)) +
+                    "\n" +
+                    `  ${green("✓")} ${dim(JSON.stringify(actual))} ${dim("⊇")} ${dim(JSON.stringify(value))}\n`);
+                return true;
+            }
+            const message = `${JSON.stringify(actual)} does not contain ${kind} ${JSON.stringify(value)}`;
+            ctx.stderr.write(bold(red(`Assert.Contains.${name}: assertion failed`)) +
+                "\n" +
+                `  ${red("✗")} ${message}\n`);
+            throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Contains "${name}": ${message}`);
+        },
+    };
+}

package/dist/deep-equals.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Deep equality for the JSON-shaped values Telo stages typically pass
+ * around: primitives, plain objects (proto === Object.prototype or null),
+ * and arrays. Non-plain objects (Date, Map, Set, RegExp, class instances)
+ * are NOT structurally compared — only `Object.is`-equal instances pass.
+ *
+ * This is intentional: structurally comparing the empty `Object.keys()`
+ * of two distinct `new Date(…)` instances would silently return true,
+ * letting `Assert.Equals` pass for values that are clearly different.
+ * If a consumer genuinely needs Date / Map / Set equality, they should
+ * serialize first (e.g. `date.toISOString()`) and compare the strings.
+ */
+export declare function deepEquals(a: unknown, b: unknown): boolean;

package/dist/deep-equals.js

@@ -0,0 +1,48 @@
+/**
+ * Deep equality for the JSON-shaped values Telo stages typically pass
+ * around: primitives, plain objects (proto === Object.prototype or null),
+ * and arrays. Non-plain objects (Date, Map, Set, RegExp, class instances)
+ * are NOT structurally compared — only `Object.is`-equal instances pass.
+ *
+ * This is intentional: structurally comparing the empty `Object.keys()`
+ * of two distinct `new Date(…)` instances would silently return true,
+ * letting `Assert.Equals` pass for values that are clearly different.
+ * If a consumer genuinely needs Date / Map / Set equality, they should
+ * serialize first (e.g. `date.toISOString()`) and compare the strings.
+ */
+export function deepEquals(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEquals(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    // Refuse structural compare for non-plain objects. Identity was already
+    // checked at the top; reaching here with a non-plain object means a !== b
+    // and we cannot meaningfully recurse into "fields" — empty keys would
+    // produce false positives.
+    if (!isPlainObject(a) || !isPlainObject(b))
+        return false;
+    const ao = a;
+    const bo = b;
+    const aKeys = Object.keys(ao);
+    const bKeys = Object.keys(bo);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k) || !deepEquals(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+function isPlainObject(v) {
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}

package/dist/equals.d.ts

@@ -0,0 +1,16 @@
+import { ResourceContext } from "@telorun/sdk";
+import { Static } from "@sinclair/typebox";
+export declare const schema: import("@sinclair/typebox").TObject<{
+    metadata: import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+    }>;
+}>;
+type AssertManifest = Static<typeof schema>;
+interface EqualsInput {
+    actual: unknown;
+    expected: unknown;
+}
+export declare function create(manifest: AssertManifest, ctx: ResourceContext): Promise<{
+    invoke: (input: EqualsInput) => boolean;
+}>;
+export {};

package/dist/equals.js

@@ -0,0 +1,29 @@
+import { InvokeError } from "@telorun/sdk";
+import { Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+import { deepEquals } from "./deep-equals.js";
+export const schema = Type.Object({
+    metadata: Type.Object({
+        name: Type.String(),
+    }),
+});
+export async function create(manifest, ctx) {
+    const { bold, red, green, dim } = createColors(ctx);
+    const name = manifest.metadata.name;
+    return {
+        invoke: (input) => {
+            const { actual, expected } = input ?? {};
+            if (deepEquals(actual, expected)) {
+                ctx.stdout.write(bold(green(`Assert.Equals.${name}: assertion passed`)) +
+                    "\n" +
+                    `  ${green("✓")} ${dim(JSON.stringify(actual))}\n`);
+                return true;
+            }
+            const message = `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+            ctx.stderr.write(bold(red(`Assert.Equals.${name}: assertion failed`)) +
+                "\n" +
+                `  ${red("✗")} ${message}\n`);
+            throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Equals "${name}": ${message}`);
+        },
+    };
+}

package/dist/matches.d.ts

@@ -0,0 +1,17 @@
+import { ResourceContext } from "@telorun/sdk";
+import { Static } from "@sinclair/typebox";
+export declare const schema: import("@sinclair/typebox").TObject<{
+    metadata: import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+    }>;
+}>;
+type AssertManifest = Static<typeof schema>;
+interface MatchesInput {
+    actual: unknown;
+    pattern: string;
+    flags?: string;
+}
+export declare function create(manifest: AssertManifest, ctx: ResourceContext): Promise<{
+    invoke: (input: MatchesInput) => boolean;
+}>;
+export {};

package/dist/matches.js

@@ -0,0 +1,45 @@
+import { InvokeError } from "@telorun/sdk";
+import { Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+export const schema = Type.Object({
+    metadata: Type.Object({
+        name: Type.String(),
+    }),
+});
+export async function create(manifest, ctx) {
+    const { bold, red, green, dim } = createColors(ctx);
+    const name = manifest.metadata.name;
+    return {
+        invoke: (input) => {
+            const { actual, pattern, flags } = input ?? {};
+            if (typeof pattern !== "string") {
+                throw new InvokeError("ERR_INVALID_CONFIG", `Assert.Matches "${name}": 'pattern' must be a string`);
+            }
+            let regex;
+            try {
+                regex = new RegExp(pattern, flags ?? "");
+            }
+            catch (err) {
+                throw new InvokeError("ERR_INVALID_CONFIG", `Assert.Matches "${name}": invalid pattern — ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (typeof actual !== "string") {
+                const message = `actual must be a string; got ${typeof actual}`;
+                ctx.stderr.write(bold(red(`Assert.Matches.${name}: assertion failed`)) +
+                    "\n" +
+                    `  ${red("✗")} ${message}\n`);
+                throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Matches "${name}": ${message}`);
+            }
+            if (regex.test(actual)) {
+                ctx.stdout.write(bold(green(`Assert.Matches.${name}: assertion passed`)) +
+                    "\n" +
+                    `  ${green("✓")} ${dim(JSON.stringify(actual))} ${dim("~")} ${dim(regex.toString())}\n`);
+                return true;
+            }
+            const message = `${JSON.stringify(actual)} does not match ${regex.toString()}`;
+            ctx.stderr.write(bold(red(`Assert.Matches.${name}: assertion failed`)) +
+                "\n" +
+                `  ${red("✗")} ${message}\n`);
+            throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Matches "${name}": ${message}`);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/assert",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "description": "Telo Assert module - Assertion resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -23,7 +23,10 @@
     "./schema": "./src/schema.ts",
     "./events": "./src/events.ts",
     "./module-context": "./src/module-context.ts",
-    "./manifest": "./src/manifest.ts"
+    "./manifest": "./src/manifest.ts",
+    "./equals": "./src/equals.ts",
+    "./matches": "./src/matches.ts",
+    "./contains": "./src/contains.ts"
   },
   "files": [
     "dist",
@@ -31,7 +34,7 @@
   ],
   "dependencies": {
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.6.0",
+    "@telorun/analyzer": "0.6.1",
     "@telorun/sdk": "0.7.0"
   },
   "devDependencies": {

package/src/colors.ts

@@ -0,0 +1,18 @@
+import type { ResourceContext } from "@telorun/sdk";
+
+/**
+ * Build the small ANSI color helpers used by every assert kind. Returns
+ * pass-through (uncolored) helpers when stderr isn't a TTY so piped /
+ * redirected output stays clean.
+ */
+export function createColors(ctx: ResourceContext) {
+  const useColor = (ctx.stderr as { isTTY?: boolean }).isTTY ?? false;
+  const c = (code: string, text: string) =>
+    useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+  return {
+    bold: (t: string) => c("1", t),
+    red: (t: string) => c("31", t),
+    green: (t: string) => c("32", t),
+    dim: (t: string) => c("2", t),
+  };
+}

package/src/contains.ts

@@ -0,0 +1,74 @@
+import { InvokeError, ResourceContext } from "@telorun/sdk";
+import { Static, Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+import { deepEquals } from "./deep-equals.js";
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+  }),
+});
+
+type AssertManifest = Static<typeof schema>;
+
+interface ContainsInput {
+  actual: unknown;
+  value: unknown;
+}
+
+export async function create(manifest: AssertManifest, ctx: ResourceContext) {
+  const { bold, red, green, dim } = createColors(ctx);
+  const name = manifest.metadata.name;
+
+  return {
+    invoke: (input: ContainsInput) => {
+      const { actual, value } = input ?? ({} as ContainsInput);
+
+      let ok = false;
+      let kind = "";
+      if (typeof actual === "string") {
+        if (typeof value !== "string") {
+          const message = `actual is a string but value is ${typeof value}; expected substring`;
+          ctx.stderr.write(
+            bold(red(`Assert.Contains.${name}: assertion failed`)) +
+              "\n" +
+              `  ${red("✗")} ${message}\n`,
+          );
+          throw new InvokeError(
+            "ERR_ASSERTION_FAILED",
+            `Assert.Contains "${name}": ${message}`,
+          );
+        }
+        kind = "substring";
+        ok = actual.includes(value);
+      } else if (Array.isArray(actual)) {
+        kind = "element";
+        ok = actual.some((item) => deepEquals(item, value));
+      } else {
+        const message = `actual must be string or array; got ${typeof actual}`;
+        ctx.stderr.write(
+          bold(red(`Assert.Contains.${name}: assertion failed`)) +
+            "\n" +
+            `  ${red("✗")} ${message}\n`,
+        );
+        throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Contains "${name}": ${message}`);
+      }
+
+      if (ok) {
+        ctx.stdout.write(
+          bold(green(`Assert.Contains.${name}: assertion passed`)) +
+            "\n" +
+            `  ${green("✓")} ${dim(JSON.stringify(actual))} ${dim("⊇")} ${dim(JSON.stringify(value))}\n`,
+        );
+        return true;
+      }
+      const message = `${JSON.stringify(actual)} does not contain ${kind} ${JSON.stringify(value)}`;
+      ctx.stderr.write(
+        bold(red(`Assert.Contains.${name}: assertion failed`)) +
+          "\n" +
+          `  ${red("✗")} ${message}\n`,
+      );
+      throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Contains "${name}": ${message}`);
+    },
+  };
+}

package/src/deep-equals.ts

@@ -0,0 +1,45 @@
+/**
+ * Deep equality for the JSON-shaped values Telo stages typically pass
+ * around: primitives, plain objects (proto === Object.prototype or null),
+ * and arrays. Non-plain objects (Date, Map, Set, RegExp, class instances)
+ * are NOT structurally compared — only `Object.is`-equal instances pass.
+ *
+ * This is intentional: structurally comparing the empty `Object.keys()`
+ * of two distinct `new Date(…)` instances would silently return true,
+ * letting `Assert.Equals` pass for values that are clearly different.
+ * If a consumer genuinely needs Date / Map / Set equality, they should
+ * serialize first (e.g. `date.toISOString()`) and compare the strings.
+ */
+export function deepEquals(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEquals(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  // Refuse structural compare for non-plain objects. Identity was already
+  // checked at the top; reaching here with a non-plain object means a !== b
+  // and we cannot meaningfully recurse into "fields" — empty keys would
+  // produce false positives.
+  if (!isPlainObject(a) || !isPlainObject(b)) return false;
+
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const aKeys = Object.keys(ao);
+  const bKeys = Object.keys(bo);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(bo, k) || !deepEquals(ao[k], bo[k])) return false;
+  }
+  return true;
+}
+
+function isPlainObject(v: object): boolean {
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}

package/src/equals.ts

@@ -0,0 +1,43 @@
+import { InvokeError, ResourceContext } from "@telorun/sdk";
+import { Static, Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+import { deepEquals } from "./deep-equals.js";
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+  }),
+});
+
+type AssertManifest = Static<typeof schema>;
+
+interface EqualsInput {
+  actual: unknown;
+  expected: unknown;
+}
+
+export async function create(manifest: AssertManifest, ctx: ResourceContext) {
+  const { bold, red, green, dim } = createColors(ctx);
+  const name = manifest.metadata.name;
+
+  return {
+    invoke: (input: EqualsInput) => {
+      const { actual, expected } = input ?? ({} as EqualsInput);
+      if (deepEquals(actual, expected)) {
+        ctx.stdout.write(
+          bold(green(`Assert.Equals.${name}: assertion passed`)) +
+            "\n" +
+            `  ${green("✓")} ${dim(JSON.stringify(actual))}\n`,
+        );
+        return true;
+      }
+      const message = `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+      ctx.stderr.write(
+        bold(red(`Assert.Equals.${name}: assertion failed`)) +
+          "\n" +
+          `  ${red("✗")} ${message}\n`,
+      );
+      throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Equals "${name}": ${message}`);
+    },
+  };
+}

package/src/matches.ts

@@ -0,0 +1,69 @@
+import { InvokeError, ResourceContext } from "@telorun/sdk";
+import { Static, Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+  }),
+});
+
+type AssertManifest = Static<typeof schema>;
+
+interface MatchesInput {
+  actual: unknown;
+  pattern: string;
+  flags?: string;
+}
+
+export async function create(manifest: AssertManifest, ctx: ResourceContext) {
+  const { bold, red, green, dim } = createColors(ctx);
+  const name = manifest.metadata.name;
+
+  return {
+    invoke: (input: MatchesInput) => {
+      const { actual, pattern, flags } = input ?? ({} as MatchesInput);
+
+      if (typeof pattern !== "string") {
+        throw new InvokeError(
+          "ERR_INVALID_CONFIG",
+          `Assert.Matches "${name}": 'pattern' must be a string`,
+        );
+      }
+      let regex: RegExp;
+      try {
+        regex = new RegExp(pattern, flags ?? "");
+      } catch (err) {
+        throw new InvokeError(
+          "ERR_INVALID_CONFIG",
+          `Assert.Matches "${name}": invalid pattern — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      if (typeof actual !== "string") {
+        const message = `actual must be a string; got ${typeof actual}`;
+        ctx.stderr.write(
+          bold(red(`Assert.Matches.${name}: assertion failed`)) +
+            "\n" +
+            `  ${red("✗")} ${message}\n`,
+        );
+        throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Matches "${name}": ${message}`);
+      }
+      if (regex.test(actual)) {
+        ctx.stdout.write(
+          bold(green(`Assert.Matches.${name}: assertion passed`)) +
+            "\n" +
+            `  ${green("✓")} ${dim(JSON.stringify(actual))} ${dim("~")} ${dim(regex.toString())}\n`,
+        );
+        return true;
+      }
+      const message = `${JSON.stringify(actual)} does not match ${regex.toString()}`;
+      ctx.stderr.write(
+        bold(red(`Assert.Matches.${name}: assertion failed`)) +
+          "\n" +
+          `  ${red("✗")} ${message}\n`,
+      );
+      throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Matches "${name}": ${message}`);
+    },
+  };
+}