ultracode-shared 1.3.0

package/dist/utils/async.js

@@ -0,0 +1,45 @@
+/**
+ * Async helpers: cancellable {@link sleep}.
+ */
+/**
+ * Resolve after `ms` milliseconds, with optional cancellation.
+ *
+ * - If `signal` is already aborted, rejects immediately with the signal's
+ *   `reason` (or an `AbortError` if none).
+ * - If `signal` aborts before the timer fires, the timer is cleared and the
+ *   promise rejects with the abort reason.
+ * - Negative or non-finite `ms` is clamped to `0`.
+ *
+ * @param ms - delay in milliseconds.
+ * @param signal - optional cancellation signal.
+ */
+export function sleep(ms, signal) {
+    const delay = Number.isFinite(ms) && ms > 0 ? ms : 0;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        let onAbort;
+        const timer = setTimeout(() => {
+            if (signal !== undefined && onAbort !== undefined) {
+                signal.removeEventListener("abort", onAbort);
+            }
+            resolve();
+        }, delay);
+        if (signal !== undefined) {
+            onAbort = () => {
+                clearTimeout(timer);
+                reject(abortReason(signal));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
+}
+/** Extract a rejection reason from an aborted signal. */
+function abortReason(signal) {
+    if (signal.reason !== undefined)
+        return signal.reason;
+    return new DOMException("The operation was aborted.", "AbortError");
+}
+//# sourceMappingURL=async.js.map

package/dist/utils/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/utils/async.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,OAAiC,CAAC;QAEtC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAClD,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,KAAK,CAAC,CAAC;QAEV,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,GAAG,GAAS,EAAE;gBACnB,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,CAAC,CAAC;YACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yDAAyD;AACzD,SAAS,WAAW,CAAC,MAAmB;IACtC,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IACtD,OAAO,IAAI,YAAY,CAAC,4BAA4B,EAAE,YAAY,CAAC,CAAC;AACtE,CAAC"}

package/dist/utils/id.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Identifier generation.
+ */
+/**
+ * Generate a unique identifier backed by `crypto.randomUUID()`.
+ *
+ * - Without a prefix: returns the bare UUID (e.g. `"f47ac10b-58cc-…"`).
+ * - With a prefix: returns `"<prefix>_<uuid>"` (e.g. `"sess_f47ac10b-…"`).
+ *
+ * @param prefix - optional namespace prefix (no trailing separator needed).
+ */
+export declare function generateId(prefix?: string): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlD"}

package/dist/utils/id.js

@@ -0,0 +1,17 @@
+/**
+ * Identifier generation.
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * Generate a unique identifier backed by `crypto.randomUUID()`.
+ *
+ * - Without a prefix: returns the bare UUID (e.g. `"f47ac10b-58cc-…"`).
+ * - With a prefix: returns `"<prefix>_<uuid>"` (e.g. `"sess_f47ac10b-…"`).
+ *
+ * @param prefix - optional namespace prefix (no trailing separator needed).
+ */
+export function generateId(prefix) {
+    const uuid = randomUUID();
+    return prefix !== undefined && prefix.length > 0 ? `${prefix}_${uuid}` : uuid;
+}
+//# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe;IACxC,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChF,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel for the shared utility functions.
+ */
+export { serializeError } from "./serializeError.js";
+export { truncate, DEFAULT_TRUNCATE_SUFFIX } from "./truncate.js";
+export type { TruncateOptions } from "./truncate.js";
+export { isPlainObject, deepMerge } from "./object.js";
+export { sleep } from "./async.js";
+export { clamp } from "./math.js";
+export { generateId } from "./id.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,10 @@
+/**
+ * Barrel for the shared utility functions.
+ */
+export { serializeError } from "./serializeError.js";
+export { truncate, DEFAULT_TRUNCATE_SUFFIX } from "./truncate.js";
+export { isPlainObject, deepMerge } from "./object.js";
+export { sleep } from "./async.js";
+export { clamp } from "./math.js";
+export { generateId } from "./id.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

package/dist/utils/math.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Numeric helpers.
+ */
+/**
+ * Constrain `value` to the inclusive range `[min, max]`.
+ *
+ * - `NaN` input returns `min` (defensive default).
+ * - If `min > max`, the bounds are swapped so the function is total.
+ *
+ * @param value - the value to clamp.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOrE"}

package/dist/utils/math.js

@@ -0,0 +1,25 @@
+/**
+ * Numeric helpers.
+ */
+/**
+ * Constrain `value` to the inclusive range `[min, max]`.
+ *
+ * - `NaN` input returns `min` (defensive default).
+ * - If `min > max`, the bounds are swapped so the function is total.
+ *
+ * @param value - the value to clamp.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ */
+export function clamp(value, min, max) {
+    const lo = Math.min(min, max);
+    const hi = Math.max(min, max);
+    if (Number.isNaN(value))
+        return lo;
+    if (value < lo)
+        return lo;
+    if (value > hi)
+        return hi;
+    return value;
+}
+//# sourceMappingURL=math.js.map

package/dist/utils/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IAC3D,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/object.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Object utilities: plain-object detection and a prototype-pollution-safe deep
+ * merge used to layer configuration (project over user over defaults).
+ */
+/**
+ * Maximum nesting depth `deepMerge`/`clonePlain` will recurse before failing
+ * fast with a {@link ValidationError}. Guards against stack-overflow crashes
+ * from pathologically deep (or cyclic) override trees.
+ */
+export declare const MAX_MERGE_DEPTH = 100;
+/**
+ * Whether `value` is a "plain" object: a non-null object whose prototype is
+ * `Object.prototype` or `null`. Arrays, class instances, `Date`, `Map`, etc.
+ * are rejected.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Recursively merge `override` onto `base`, returning a new object.
+ *
+ * Semantics:
+ * - Plain objects are merged key-by-key, recursively.
+ * - **Arrays are replaced wholesale**, never concatenated or element-merged.
+ * - `undefined` values in `override` are skipped (they do not erase `base`).
+ *   `null` values *do* overwrite (an explicit "set to null").
+ * - Non-plain objects (class instances, `Date`, `Map`, …) in `override` replace
+ *   the corresponding `base` value wholesale.
+ * - **Prototype pollution is prevented**: keys `__proto__`, `constructor` and
+ *   `prototype` are never copied, and only own-enumerable string keys are read.
+ *
+ * Neither input is mutated. The result is a fresh, null-prototype-free object
+ * tree for the merged portions.
+ *
+ * @typeParam T - the (resolved) shape of the base object.
+ */
+export declare function deepMerge<T>(base: T, override: unknown): T;
+//# sourceMappingURL=object.d.ts.map

package/dist/utils/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;GAIG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAK9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,CAAC,CAE1D"}

package/dist/utils/object.js

@@ -0,0 +1,122 @@
+/**
+ * Object utilities: plain-object detection and a prototype-pollution-safe deep
+ * merge used to layer configuration (project over user over defaults).
+ */
+import { ValidationError } from "../errors.js";
+/** Keys that must never be assigned during a merge (prototype-pollution guard). */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Maximum nesting depth `deepMerge`/`clonePlain` will recurse before failing
+ * fast with a {@link ValidationError}. Guards against stack-overflow crashes
+ * from pathologically deep (or cyclic) override trees.
+ */
+export const MAX_MERGE_DEPTH = 100;
+/**
+ * Whether `value` is a "plain" object: a non-null object whose prototype is
+ * `Object.prototype` or `null`. Arrays, class instances, `Date`, `Map`, etc.
+ * are rejected.
+ */
+export function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Recursively merge `override` onto `base`, returning a new object.
+ *
+ * Semantics:
+ * - Plain objects are merged key-by-key, recursively.
+ * - **Arrays are replaced wholesale**, never concatenated or element-merged.
+ * - `undefined` values in `override` are skipped (they do not erase `base`).
+ *   `null` values *do* overwrite (an explicit "set to null").
+ * - Non-plain objects (class instances, `Date`, `Map`, …) in `override` replace
+ *   the corresponding `base` value wholesale.
+ * - **Prototype pollution is prevented**: keys `__proto__`, `constructor` and
+ *   `prototype` are never copied, and only own-enumerable string keys are read.
+ *
+ * Neither input is mutated. The result is a fresh, null-prototype-free object
+ * tree for the merged portions.
+ *
+ * @typeParam T - the (resolved) shape of the base object.
+ */
+export function deepMerge(base, override) {
+    return deepMergeAt(base, override, 0);
+}
+/** Recursive worker for {@link deepMerge}; tracks nesting `depth`. */
+function deepMergeAt(base, override, depth) {
+    if (depth > MAX_MERGE_DEPTH) {
+        throw new ValidationError(`deepMerge exceeded maximum nesting depth of ${MAX_MERGE_DEPTH} ` +
+            `(cyclic or pathologically deep override)`, { details: { maxDepth: MAX_MERGE_DEPTH } });
+    }
+    // Non-mergeable override (primitive, array, class instance) wins outright,
+    // unless it is `undefined` (treated as "no override").
+    if (override === undefined)
+        return clonePlainAt(base, depth, new WeakSet());
+    if (!isPlainObject(base) || !isPlainObject(override)) {
+        return clonePlainAt(override, depth, new WeakSet());
+    }
+    const out = clonePlainAt(base, depth, new WeakSet());
+    for (const key of Object.keys(override)) {
+        if (FORBIDDEN_KEYS.has(key))
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(override, key))
+            continue;
+        const overrideVal = override[key];
+        if (overrideVal === undefined)
+            continue; // skip, keep base
+        const baseVal = out[key];
+        if (isPlainObject(baseVal) && isPlainObject(overrideVal)) {
+            out[key] = deepMergeAt(baseVal, overrideVal, depth + 1);
+        }
+        else {
+            out[key] = clonePlainAt(overrideVal, depth + 1, new WeakSet());
+        }
+    }
+    return out;
+}
+/**
+ * Shallow-recursive clone that copies plain objects and arrays while leaving
+ * other values (primitives, class instances) by reference. Drops forbidden keys.
+ * Tracks nesting `depth` and the chain of `seen` containers (cycle guard).
+ *
+ * Cyclic references and pathologically deep trees are rejected with a
+ * {@link ValidationError} rather than crashing the stack.
+ */
+function clonePlainAt(value, depth, seen) {
+    if (depth > MAX_MERGE_DEPTH) {
+        throw new ValidationError(`deepMerge exceeded maximum nesting depth of ${MAX_MERGE_DEPTH} ` +
+            `(cyclic or pathologically deep override)`, { details: { maxDepth: MAX_MERGE_DEPTH } });
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            throw new ValidationError("deepMerge detected a circular reference", {
+                details: { kind: "array" },
+            });
+        }
+        seen.add(value);
+        const cloned = value.map((item) => clonePlainAt(item, depth + 1, seen));
+        seen.delete(value);
+        return cloned;
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value)) {
+            throw new ValidationError("deepMerge detected a circular reference", {
+                details: { kind: "object" },
+            });
+        }
+        seen.add(value);
+        const out = {};
+        for (const key of Object.keys(value)) {
+            if (FORBIDDEN_KEYS.has(key))
+                continue;
+            out[key] = clonePlainAt(value[key], depth + 1, seen);
+        }
+        seen.delete(value);
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=object.js.map

package/dist/utils/object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.js","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"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"}

package/dist/utils/serializeError.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reduce an arbitrary thrown value to a stable, JSON-safe {@link SerializedError}.
+ *
+ * Handles {@link UltraCodeError} (preserving its `code`), plain `Error`s,
+ * string/primitive throws, and structurally error-shaped objects. Never throws.
+ */
+import type { SerializedError } from "../errors.js";
+/**
+ * Convert any caught value into a {@link SerializedError}.
+ *
+ * @param err - the thrown value (may be anything).
+ * @returns a JSON-safe error descriptor with at least `name`, `message`, `code`.
+ */
+export declare function serializeError(err: unknown): SerializedError;
+//# sourceMappingURL=serializeError.d.ts.map

package/dist/utils/serializeError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializeError.d.ts","sourceRoot":"","sources":["../../src/utils/serializeError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAQpD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAwC5D"}

package/dist/utils/serializeError.js

@@ -0,0 +1,69 @@
+/**
+ * Reduce an arbitrary thrown value to a stable, JSON-safe {@link SerializedError}.
+ *
+ * Handles {@link UltraCodeError} (preserving its `code`), plain `Error`s,
+ * string/primitive throws, and structurally error-shaped objects. Never throws.
+ */
+import { UltraCodeError } from "../errors.js";
+/** Type guard for objects that look like an `Error`. */
+function isErrorLike(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Convert any caught value into a {@link SerializedError}.
+ *
+ * @param err - the thrown value (may be anything).
+ * @returns a JSON-safe error descriptor with at least `name`, `message`, `code`.
+ */
+export function serializeError(err) {
+    // UltraCodeError already knows how to serialise itself.
+    if (err instanceof UltraCodeError) {
+        return err.toJSON();
+    }
+    if (err instanceof Error) {
+        const out = {
+            name: err.name || "Error",
+            message: err.message,
+            code: typeof err.code === "string"
+                ? err.code
+                : "ERROR",
+        };
+        if (typeof err.stack === "string")
+            out.stack = err.stack;
+        return out;
+    }
+    // String throws: `throw "boom"`.
+    if (typeof err === "string") {
+        return { name: "Error", message: err, code: "ERROR" };
+    }
+    // Error-shaped plain objects (e.g. structured-clone survivors).
+    if (isErrorLike(err)) {
+        const name = typeof err.name === "string" ? err.name : "Error";
+        const message = typeof err.message === "string" ? err.message : safeStringify(err);
+        const out = {
+            name,
+            message,
+            code: typeof err.code === "string" ? err.code : "ERROR",
+        };
+        if (typeof err.stack === "string")
+            out.stack = err.stack;
+        return out;
+    }
+    // Fallback for numbers, booleans, null, undefined, symbols, bigints.
+    return { name: "Error", message: safeStringify(err), code: "ERROR" };
+}
+/** `JSON.stringify` that degrades gracefully and never throws. */
+function safeStringify(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    try {
+        const s = JSON.stringify(value);
+        return s ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=serializeError.js.map

package/dist/utils/serializeError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializeError.js","sourceRoot":"","sources":["../../src/utils/serializeError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,wDAAwD;AACxD,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,wDAAwD;IACxD,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;IAED,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAoB;YAC3B,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,OAAO;YACzB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,IAAI,EACF,OAAQ,GAAqC,CAAC,IAAI,KAAK,QAAQ;gBAC7D,CAAC,CAAE,GAAmC,CAAC,IAAI;gBAC3C,CAAC,CAAC,OAAO;SACd,CAAC;QACF,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACzD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iCAAiC;IACjC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACxD,CAAC;IAED,gEAAgE;IAChE,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;QAC/D,MAAM,OAAO,GACX,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACrE,MAAM,GAAG,GAAoB;YAC3B,IAAI;YACJ,OAAO;YACP,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;SACxD,CAAC;QACF,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACzD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,qEAAqE;IACrE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACvE,CAAC;AAED,kEAAkE;AAClE,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC5C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/utils/truncate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Unicode-safe string truncation.
+ *
+ * Truncation respects Unicode code points (so a surrogate pair / emoji is never
+ * split in half) and appends an ellipsis suffix that is included in the budget.
+ */
+/** Default suffix appended when a string is truncated. */
+export declare const DEFAULT_TRUNCATE_SUFFIX = "\u2026";
+/** Options for {@link truncate}. */
+export interface TruncateOptions {
+    /** Suffix appended on truncation. Defaults to `"…"`. */
+    suffix?: string;
+}
+/**
+ * Truncate `s` so the result is at most `max` code points long.
+ *
+ * - If `s` already fits, it is returned unchanged.
+ * - If `max <= 0`, the empty string is returned.
+ * - The `suffix` counts toward `max`; if the suffix alone exceeds `max`, the
+ *   suffix itself is code-point-truncated to fit.
+ * - Counting and slicing operate on code points (via the string iterator), so
+ *   emoji and other astral-plane characters are never cut mid-pair.
+ *
+ * @param s - input string.
+ * @param max - maximum length in Unicode code points.
+ * @param options - truncation options.
+ */
+export declare function truncate(s: string, max: number, options?: TruncateOptions): string;
+//# sourceMappingURL=truncate.d.ts.map

package/dist/utils/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../src/utils/truncate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,WAAM,CAAC;AAE3C,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAmBtF"}

package/dist/utils/truncate.js

@@ -0,0 +1,42 @@
+/**
+ * Unicode-safe string truncation.
+ *
+ * Truncation respects Unicode code points (so a surrogate pair / emoji is never
+ * split in half) and appends an ellipsis suffix that is included in the budget.
+ */
+/** Default suffix appended when a string is truncated. */
+export const DEFAULT_TRUNCATE_SUFFIX = "…";
+/**
+ * Truncate `s` so the result is at most `max` code points long.
+ *
+ * - If `s` already fits, it is returned unchanged.
+ * - If `max <= 0`, the empty string is returned.
+ * - The `suffix` counts toward `max`; if the suffix alone exceeds `max`, the
+ *   suffix itself is code-point-truncated to fit.
+ * - Counting and slicing operate on code points (via the string iterator), so
+ *   emoji and other astral-plane characters are never cut mid-pair.
+ *
+ * @param s - input string.
+ * @param max - maximum length in Unicode code points.
+ * @param options - truncation options.
+ */
+export function truncate(s, max, options = {}) {
+    if (max <= 0)
+        return "";
+    // Fast path: byte/unit length is an upper bound on code-point count, so if it
+    // already fits there is no possible truncation. Avoids iterating huge strings.
+    if (s.length <= max)
+        return s;
+    const suffix = options.suffix ?? DEFAULT_TRUNCATE_SUFFIX;
+    const codePoints = Array.from(s);
+    if (codePoints.length <= max)
+        return s;
+    const suffixPoints = Array.from(suffix);
+    // If the suffix cannot fit, truncate the suffix itself.
+    if (suffixPoints.length >= max) {
+        return suffixPoints.slice(0, max).join("");
+    }
+    const keep = max - suffixPoints.length;
+    return codePoints.slice(0, keep).join("") + suffix;
+}
+//# sourceMappingURL=truncate.js.map

package/dist/utils/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/utils/truncate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAQ3C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,GAAW,EAAE,UAA2B,EAAE;IAC5E,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAExB,8EAA8E;IAC9E,+EAA+E;IAC/E,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAE9B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,uBAAuB,CAAC;IACzD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,UAAU,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAEvC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,IAAI,YAAY,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC/B,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC;IACvC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;AACrD,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ultracode-shared",
+  "version": "1.3.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Shared types, contracts, errors and utilities for UltraCode",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndreasSchwan-SIMO/UltraCode.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://github.com/AndreasSchwan-SIMO/UltraCode#readme",
+  "bugs": {
+    "url": "https://github.com/AndreasSchwan-SIMO/UltraCode/issues"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}