@stackables/bridge-stdlib 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stackables
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @stackables/bridge-stdlib — Bridge standard library tools.
+ *
+ * Contains the `std` namespace tools (httpCall, string helpers, array helpers,
+ * audit, assert) that ship with Bridge.  Referenced in `.bridge` files as
+ * `std.httpCall`, `std.str.toUpperCase`, etc.
+ *
+ * Separated from core so it can be versioned independently.
+ */
+import { audit } from "./tools/audit.ts";
+import * as arrays from "./tools/arrays.ts";
+import * as strings from "./tools/strings.ts";
+import { assert } from "./tools/assert.ts";
+export declare const std: {
+    readonly str: typeof strings;
+    readonly arr: typeof arrays;
+    readonly audit: typeof audit;
+    readonly httpCall: import("@stackables/bridge-types").ToolCallFn;
+    readonly assert: typeof assert;
+};
+/**
+ * All known built-in tool names as "namespace.tool" strings.
+ *
+ * Useful for LSP/IDE autocomplete and diagnostics.
+ */
+export declare const builtinToolNames: readonly string[];
+export { createHttpCall } from "./tools/http-call.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAS3C,eAAO,MAAM,GAAG;;;;;;CAMN,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAE7C,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/build/index.js

@@ -0,0 +1,34 @@
+/**
+ * @stackables/bridge-stdlib — Bridge standard library tools.
+ *
+ * Contains the `std` namespace tools (httpCall, string helpers, array helpers,
+ * audit, assert) that ship with Bridge.  Referenced in `.bridge` files as
+ * `std.httpCall`, `std.str.toUpperCase`, etc.
+ *
+ * Separated from core so it can be versioned independently.
+ */
+import { audit } from "./tools/audit.js";
+import { createHttpCall } from "./tools/http-call.js";
+import * as arrays from "./tools/arrays.js";
+import * as strings from "./tools/strings.js";
+import { assert } from "./tools/assert.js";
+/**
+ * Standard built-in tools — available under the `std` namespace.
+ *
+ * Referenced in `.bridge` files as `std.str.toUpperCase`, `std.arr.first`, etc.
+ */
+const httpCallFn = createHttpCall();
+export const std = {
+    str: strings,
+    arr: arrays,
+    audit,
+    httpCall: httpCallFn,
+    assert,
+};
+/**
+ * All known built-in tool names as "namespace.tool" strings.
+ *
+ * Useful for LSP/IDE autocomplete and diagnostics.
+ */
+export const builtinToolNames = Object.keys(std).map((k) => `std.${k}`);
+export { createHttpCall } from "./tools/http-call.js";

package/build/tools/arrays.d.ts

@@ -0,0 +1,28 @@
+export declare function filter(opts: {
+    in: any[];
+    [key: string]: any;
+}): any[];
+export declare function find(opts: {
+    in: any[];
+    [key: string]: any;
+}): any;
+/**
+ * Returns the first element of the array in `opts.in`.
+ *
+ * By default silently returns `undefined` for empty arrays.
+ * Set `opts.strict` to `true` (or the string "true") to throw when
+ * the array is empty or contains more than one element.
+ */
+export declare function first(opts: {
+    in: any[];
+    strict?: boolean | string;
+}): any;
+/**
+ * Wraps a single value in an array.
+ *
+ * If `opts.in` is already an array it is returned as-is.
+ */
+export declare function toArray(opts: {
+    in: any;
+}): any[];
+//# sourceMappingURL=arrays.d.ts.map

package/build/tools/arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../../src/tools/arrays.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,SAU7D;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,OAU3D;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,OAgBnE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,CAAA;CAAE,SAExC"}

package/build/tools/arrays.js

@@ -0,0 +1,50 @@
+export function filter(opts) {
+    const { in: arr, ...criteria } = opts;
+    return arr.filter((obj) => {
+        for (const [key, value] of Object.entries(criteria)) {
+            if (obj[key] !== value) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export function find(opts) {
+    const { in: arr, ...criteria } = opts;
+    return arr.find((obj) => {
+        for (const [key, value] of Object.entries(criteria)) {
+            if (obj[key] !== value) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+/**
+ * Returns the first element of the array in `opts.in`.
+ *
+ * By default silently returns `undefined` for empty arrays.
+ * Set `opts.strict` to `true` (or the string "true") to throw when
+ * the array is empty or contains more than one element.
+ */
+export function first(opts) {
+    const arr = opts.in;
+    const strict = opts.strict === true || opts.strict === "true";
+    if (strict) {
+        if (!Array.isArray(arr) || arr.length === 0) {
+            throw new Error("pickFirst: expected a non-empty array");
+        }
+        if (arr.length > 1) {
+            throw new Error(`pickFirst: expected exactly one element but got ${arr.length}`);
+        }
+    }
+    return Array.isArray(arr) ? arr[0] : undefined;
+}
+/**
+ * Wraps a single value in an array.
+ *
+ * If `opts.in` is already an array it is returned as-is.
+ */
+export function toArray(opts) {
+    return Array.isArray(opts.in) ? opts.in : [opts.in];
+}

package/build/tools/assert.d.ts

@@ -0,0 +1,5 @@
+import type { ToolContext } from "@stackables/bridge-types";
+export declare function assert(input: {
+    in: any;
+}, _context?: ToolContext): any;
+//# sourceMappingURL=assert.d.ts.map

package/build/tools/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/tools/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,GAAG,CAAA;CAAE,EAAE,QAAQ,CAAC,EAAE,WAAW,OAKhE"}

package/build/tools/assert.js

@@ -0,0 +1,6 @@
+export function assert(input, _context) {
+    if (!input.in) {
+        throw new Error("Assertion failed: input is falsy");
+    }
+    return input.in;
+}

package/build/tools/audit.d.ts

@@ -0,0 +1,36 @@
+import type { ToolContext } from "@stackables/bridge-types";
+/**
+ * Built-in audit tool — logs all inputs via the engine logger.
+ *
+ * Designed for use with `force` — wire any number of inputs,
+ * force the handle, and every key-value pair is logged.
+ *
+ * The logger comes from the engine's `ToolContext` (configured via
+ * `BridgeOptions.logger`).  When no logger is configured the engine's
+ * default no-op logger applies — nothing is logged.
+ *
+ * Structured logging style: data object first, message tag last.
+ *
+ * The log level defaults to `info` but can be overridden via `level` input:
+ * ```bridge
+ * audit.level = "warn"
+ * ```
+ *
+ * ```bridge
+ * bridge Mutation.createOrder {
+ *   with std.audit as audit
+ *   with orderApi as api
+ *   with input as i
+ *   with output as o
+ *
+ *   api.userId <- i.userId
+ *   audit.action = "createOrder"
+ *   audit.userId <- i.userId
+ *   audit.orderId <- api.id
+ *   force audit
+ *   o.id <- api.id
+ * }
+ * ```
+ */
+export declare function audit(input: Record<string, any>, context?: ToolContext): Record<string, any>;
+//# sourceMappingURL=audit.d.ts.map

package/build/tools/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/tools/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,uBAKtE"}

package/build/tools/audit.js

@@ -0,0 +1,39 @@
+/**
+ * Built-in audit tool — logs all inputs via the engine logger.
+ *
+ * Designed for use with `force` — wire any number of inputs,
+ * force the handle, and every key-value pair is logged.
+ *
+ * The logger comes from the engine's `ToolContext` (configured via
+ * `BridgeOptions.logger`).  When no logger is configured the engine's
+ * default no-op logger applies — nothing is logged.
+ *
+ * Structured logging style: data object first, message tag last.
+ *
+ * The log level defaults to `info` but can be overridden via `level` input:
+ * ```bridge
+ * audit.level = "warn"
+ * ```
+ *
+ * ```bridge
+ * bridge Mutation.createOrder {
+ *   with std.audit as audit
+ *   with orderApi as api
+ *   with input as i
+ *   with output as o
+ *
+ *   api.userId <- i.userId
+ *   audit.action = "createOrder"
+ *   audit.userId <- i.userId
+ *   audit.orderId <- api.id
+ *   force audit
+ *   o.id <- api.id
+ * }
+ * ```
+ */
+export function audit(input, context) {
+    const { level = "info", ...data } = input;
+    const log = context?.logger?.[level];
+    log?.(data, "[bridge:audit]");
+    return input;
+}

package/build/tools/http-call.d.ts

@@ -0,0 +1,35 @@
+import type { CacheStore, ToolCallFn } from "@stackables/bridge-types";
+/**
+ * Parse TTL (in seconds) from HTTP response headers.
+ *
+ * Priority: `Cache-Control: s-maxage` > `Cache-Control: max-age` > `Expires`.
+ * Returns 0 if the response is uncacheable (no-store, no-cache, or no headers).
+ */
+declare function parseCacheTTL(response: Response): number;
+/**
+ * Create an httpCall tool function — the built-in REST API tool.
+ *
+ * Receives a fully-built input object from the engine and makes an HTTP call.
+ * The engine resolves all wires (from tool definition + bridge wires) before calling.
+ *
+ * Expected input shape:
+ *   { baseUrl, method?, path?, headers?, cache?, ...shorthandFields }
+ *
+ * Routing rules:
+ *   - GET: shorthand fields → query string parameters
+ *   - POST/PUT/PATCH/DELETE: shorthand fields → JSON body
+ *   - `headers` object passed as HTTP headers
+ *   - `baseUrl` + `path` concatenated for the URL
+ *
+ * Cache modes:
+ *   - `cache = "auto"` (default) — respect HTTP Cache-Control / Expires headers
+ *   - `cache = 0` — disable caching entirely
+ *   - `cache = <seconds>` — explicit TTL override, ignores response headers
+ *
+ * @param fetchFn - Fetch implementation (override for testing)
+ * @param cacheStore - Pluggable cache store (default: in-memory LRU, 1024 entries)
+ */
+export declare function createHttpCall(fetchFn?: typeof fetch, cacheStore?: CacheStore): ToolCallFn;
+/** Exported for testing. */
+export { parseCacheTTL };
+//# sourceMappingURL=http-call.d.ts.map

package/build/tools/http-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-call.d.ts","sourceRoot":"","sources":["../../src/tools/http-call.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAgBvE;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAejD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,OAAO,KAAwB,EACxC,UAAU,GAAE,UAAgC,GAC3C,UAAU,CAkEZ;AAED,4BAA4B;AAC5B,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/build/tools/http-call.js

@@ -0,0 +1,118 @@
+import { LRUCache } from "lru-cache";
+/** Default in-memory LRU cache with per-entry TTL. */
+function createMemoryCache(maxEntries = 1024) {
+    const lru = new LRUCache({ max: maxEntries });
+    return {
+        get(key) {
+            return lru.get(key);
+        },
+        set(key, value, ttlSeconds) {
+            if (ttlSeconds <= 0)
+                return;
+            lru.set(key, value, { ttl: ttlSeconds * 1000 });
+        },
+    };
+}
+/**
+ * Parse TTL (in seconds) from HTTP response headers.
+ *
+ * Priority: `Cache-Control: s-maxage` > `Cache-Control: max-age` > `Expires`.
+ * Returns 0 if the response is uncacheable (no-store, no-cache, or no headers).
+ */
+function parseCacheTTL(response) {
+    const cc = response.headers.get("cache-control");
+    if (cc) {
+        if (/\bno-store\b/i.test(cc) || /\bno-cache\b/i.test(cc))
+            return 0;
+        const sMax = cc.match(/\bs-maxage\s*=\s*(\d+)\b/i);
+        if (sMax)
+            return Number(sMax[1]);
+        const max = cc.match(/\bmax-age\s*=\s*(\d+)\b/i);
+        if (max)
+            return Number(max[1]);
+    }
+    const expires = response.headers.get("expires");
+    if (expires) {
+        const delta = Math.floor((new Date(expires).getTime() - Date.now()) / 1000);
+        return delta > 0 ? delta : 0;
+    }
+    return 0;
+}
+/**
+ * Create an httpCall tool function — the built-in REST API tool.
+ *
+ * Receives a fully-built input object from the engine and makes an HTTP call.
+ * The engine resolves all wires (from tool definition + bridge wires) before calling.
+ *
+ * Expected input shape:
+ *   { baseUrl, method?, path?, headers?, cache?, ...shorthandFields }
+ *
+ * Routing rules:
+ *   - GET: shorthand fields → query string parameters
+ *   - POST/PUT/PATCH/DELETE: shorthand fields → JSON body
+ *   - `headers` object passed as HTTP headers
+ *   - `baseUrl` + `path` concatenated for the URL
+ *
+ * Cache modes:
+ *   - `cache = "auto"` (default) — respect HTTP Cache-Control / Expires headers
+ *   - `cache = 0` — disable caching entirely
+ *   - `cache = <seconds>` — explicit TTL override, ignores response headers
+ *
+ * @param fetchFn - Fetch implementation (override for testing)
+ * @param cacheStore - Pluggable cache store (default: in-memory LRU, 1024 entries)
+ */
+export function createHttpCall(fetchFn = globalThis.fetch, cacheStore = createMemoryCache()) {
+    return async (input) => {
+        const { baseUrl = "", method = "GET", path = "", headers: inputHeaders = {}, cache: cacheMode = "auto", ...rest } = input;
+        // Build URL
+        const url = new URL(baseUrl + path);
+        // Collect headers
+        const headers = {};
+        for (const [key, value] of Object.entries(inputHeaders)) {
+            if (value != null)
+                headers[key] = String(value);
+        }
+        // GET: shorthand fields → query string
+        if (method === "GET") {
+            for (const [key, value] of Object.entries(rest)) {
+                if (value != null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        // Non-GET: shorthand fields → JSON body
+        let body;
+        if (method !== "GET") {
+            const bodyObj = {};
+            for (const [key, value] of Object.entries(rest)) {
+                if (value != null)
+                    bodyObj[key] = value;
+            }
+            if (Object.keys(bodyObj).length > 0) {
+                body = JSON.stringify(bodyObj);
+                headers["Content-Type"] ??= "application/json";
+            }
+        }
+        // cache = 0 → no caching at all
+        const mode = String(cacheMode);
+        if (mode === "0") {
+            const response = await fetchFn(url.toString(), { method, headers, body });
+            return response.json();
+        }
+        const cacheKey = method + " " + url.toString() + (body ?? "");
+        // Check cache before fetching
+        const cached = await cacheStore.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const response = await fetchFn(url.toString(), { method, headers, body });
+        const data = (await response.json());
+        // Determine TTL
+        const ttl = mode === "auto" ? parseCacheTTL(response) : Number(mode);
+        if (ttl > 0) {
+            await cacheStore.set(cacheKey, data, ttl);
+        }
+        return data;
+    };
+}
+/** Exported for testing. */
+export { parseCacheTTL };

package/build/tools/strings.d.ts

@@ -0,0 +1,13 @@
+export declare function toLowerCase(opts: {
+    in: string;
+}): string;
+export declare function toUpperCase(opts: {
+    in: string;
+}): string;
+export declare function trim(opts: {
+    in: string;
+}): string;
+export declare function length(opts: {
+    in: string;
+}): number;
+//# sourceMappingURL=strings.d.ts.map

package/build/tools/strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/tools/strings.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAE/C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAE/C;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAExC;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAE1C"}

package/build/tools/strings.js

@@ -0,0 +1,12 @@
+export function toLowerCase(opts) {
+    return opts.in?.toLowerCase();
+}
+export function toUpperCase(opts) {
+    return opts.in?.toUpperCase();
+}
+export function trim(opts) {
+    return opts.in?.trim();
+}
+export function length(opts) {
+    return opts.in?.length;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@stackables/bridge-stdlib",
+  "version": "0.0.1",
+  "description": "Bridge standard library — httpCall, string, array, audit, and assert tools",
+  "main": "./build/index.js",
+  "type": "module",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stackables/bridge.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "lru-cache": "^11.2.6",
+    "@stackables/bridge-types": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --experimental-transform-types --conditions source --test test/*.test.ts"
+  }
+}