@gobing-ai/ts-utils 0.2.8 → 0.3.0

package/dist/api-response.d.ts

@@ -44,4 +44,14 @@ export declare function unauthorizedResponse(message?: string, details?: unknown
 export declare function forbiddenResponse(message?: string, details?: unknown): ApiErrorEnvelope;
 export declare function conflictResponse(message?: string, details?: unknown): ApiErrorEnvelope;
 export declare function internalErrorResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+/**
+ * Bridge a thrown error to an API error envelope — the single mapping from the domain error layer
+ * ({@link AppError}) to the wire layer ({@link ApiErrorEnvelope}). Use this in request handlers
+ * instead of hand-mapping `catch` blocks, so HTTP codes stay consistent across endpoints.
+ *
+ * A known {@link AppError} maps to its HTTP code; client-safe codes surface their message, while
+ * `Internal` and any non-`AppError` collapse to an opaque 500 that leaks neither message nor stack.
+ * Pass `details` only when you intend it to reach the client (e.g. validation field errors).
+ */
+export declare function toApiResponse(error: unknown, details?: unknown): ApiErrorEnvelope;
 //# sourceMappingURL=api-response.d.ts.map

package/dist/api-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAElF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;AAEtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAOtF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAgC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAOvG;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EACzD,OAAO,SAAgC,GACxC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAQzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAahG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,SAAuB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEpG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,SAAsB,GAAG,gBAAgB,CAEzG;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEvF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,SAA4B,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,iBAAiB,CAAC,OAAO,SAAqB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEnG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEnG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,SAA0B,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAE5G"}
+{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAElF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;AAEtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAOtF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAgC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAOvG;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EACzD,OAAO,SAAgC,GACxC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAQzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAahG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,SAAuB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEpG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,SAAsB,GAAG,gBAAgB,CAEzG;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEvF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,SAA4B,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,iBAAiB,CAAC,OAAO,SAAqB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEnG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEnG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,SAA0B,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAE5G;AAcD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAOjF"}

package/dist/api-response.js

@@ -1,3 +1,4 @@
+import { ErrorCode, isAppError } from './errors.js';
 export const API_ERROR_CODES = {
     SUCCESS: 0,
     NOT_FOUND: 404,
@@ -66,3 +67,30 @@ export function conflictResponse(message = 'Resource conflict', details) {
 export function internalErrorResponse(message = 'Internal server error', details) {
     return errorResponse(API_ERROR_CODES.INTERNAL_ERROR, message, details);
 }
+/** Maps each domain {@link ErrorCode} to its HTTP-layer {@link ApiErrorCode}. */
+const ERROR_CODE_TO_HTTP = {
+    [ErrorCode.NotFound]: API_ERROR_CODES.NOT_FOUND,
+    [ErrorCode.Validation]: API_ERROR_CODES.VALIDATION_ERROR,
+    [ErrorCode.Conflict]: API_ERROR_CODES.CONFLICT,
+    [ErrorCode.Internal]: API_ERROR_CODES.INTERNAL_ERROR,
+};
+// Client-actionable errors whose message is safe to surface. Internal/unknown errors are opaque:
+// their message (and any `cause`) must never reach the client, to avoid leaking implementation detail.
+const CLIENT_SAFE_CODES = new Set([ErrorCode.NotFound, ErrorCode.Validation, ErrorCode.Conflict]);
+/**
+ * Bridge a thrown error to an API error envelope — the single mapping from the domain error layer
+ * ({@link AppError}) to the wire layer ({@link ApiErrorEnvelope}). Use this in request handlers
+ * instead of hand-mapping `catch` blocks, so HTTP codes stay consistent across endpoints.
+ *
+ * A known {@link AppError} maps to its HTTP code; client-safe codes surface their message, while
+ * `Internal` and any non-`AppError` collapse to an opaque 500 that leaks neither message nor stack.
+ * Pass `details` only when you intend it to reach the client (e.g. validation field errors).
+ */
+export function toApiResponse(error, details) {
+    if (isAppError(error)) {
+        const httpCode = ERROR_CODE_TO_HTTP[error.code];
+        const message = CLIENT_SAFE_CODES.has(error.code) ? error.message : 'Internal server error';
+        return errorResponse(httpCode, message, CLIENT_SAFE_CODES.has(error.code) ? details : undefined);
+    }
+    return internalErrorResponse();
+}

package/dist/cursor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAY/F;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAmB9E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEvD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEhE;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC/E,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACjB;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAc1D"}
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAY/F;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAmB9E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEvD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAKhE;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC/E,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACjB;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAc1D"}

package/dist/cursor.js

@@ -1,4 +1,9 @@
 import { toMs } from './date.js';
+/**
+ * Upper bound on an encoded cursor. Cursors are short by construction (id + two numbers); a longer
+ * input is hostile (cursors are client-supplied pagination tokens) and is rejected before decode.
+ */
+const MAX_ENCODED_CURSOR_LENGTH = 1024;
 export function createCursor(id, createdAt, offset) {
     const cursor = { id };
     if (createdAt !== undefined) {
@@ -30,20 +35,18 @@ export function parseCursor(data) {
     return result;
 }
 export function encodeCursor(cursor) {
-    return Buffer.from(JSON.stringify(cursor)).toString('base64url');
+    return base64UrlEncode(JSON.stringify(cursor));
 }
 export function decodeCursor(encoded) {
-    try {
-        return Buffer.from(encoded, 'base64url').toString('utf-8');
-    }
-    catch (error) {
-        throw new Error(`Invalid cursor encoding: ${String(error)}`);
-    }
+    return base64UrlDecode(encoded);
 }
 export function encodeCursorFromItem(id, createdAt, offset) {
     return encodeCursor(createCursor(id, createdAt, offset));
 }
 export function decodeAndParseCursor(encoded) {
+    if (encoded.length > MAX_ENCODED_CURSOR_LENGTH) {
+        throw new Error('Invalid cursor: exceeds maximum length');
+    }
     return parseCursor(decodeCursor(encoded));
 }
 export function buildCursorMeta(items, limit, hasMore) {
@@ -59,3 +62,25 @@ export function buildCursorMeta(items, limit, hasMore) {
     }
     return meta;
 }
+// Web-standard base64url codec via `btoa`/`atob` (available on Node, Bun, and Cloudflare Workers) —
+// avoids node-only `Buffer` so cursors work in every runtime that depends on ts-utils.
+function base64UrlEncode(text) {
+    // Encode to UTF-8 bytes first, then to a binary string `btoa` accepts (it only handles latin1).
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+function base64UrlDecode(encoded) {
+    const base64 = encoded.replaceAll('-', '+').replaceAll('_', '/');
+    let binary;
+    try {
+        binary = atob(base64);
+    }
+    catch {
+        throw new Error('Invalid cursor encoding: not valid base64url');
+    }
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}

package/dist/date.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../src/date.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQpF;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAGjE"}
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../src/date.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CASpF;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAGjE"}

package/dist/date.js

@@ -10,7 +10,8 @@ export function toMs(input) {
         const parsed = new Date(input).getTime();
         return Number.isNaN(parsed) ? null : parsed;
     }
-    return Math.floor(input);
+    // Reject NaN/±Infinity rather than passing them through as a "valid" timestamp.
+    return Number.isFinite(input) ? Math.floor(input) : null;
 }
 export function fromMs(ms) {
     if (ms === null || ms === undefined || Number.isNaN(ms))

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './const';
 export * from './cursor';
 export * from './date';
 export * from './errors';
+export * from './object';
 export * from './origin';
 export * from './output';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export * from './const.js';
 export * from './cursor.js';
 export * from './date.js';
 export * from './errors.js';
+export * from './object.js';
 export * from './origin.js';
 export * from './output.js';

package/dist/object.d.ts

@@ -0,0 +1,19 @@
+/** Narrow to a non-array object literal. Excludes arrays and `null`, unlike a bare `typeof === object`. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Recursively merge `source` into `target`, returning a new object. Nested plain objects merge;
+ * arrays and scalars from `source` replace the target wholesale (a source array overrides, never
+ * extends). Inputs are not mutated.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Flatten a nested object into dot-delimited keys with JSON-stringified leaf values — e.g.
+ * `{ a: { b: 1 } }` → `{ "a.b": "1" }`. Inverse of {@link deFlattenKeys}.
+ */
+export declare function flattenKeys(obj: Record<string, unknown>, prefix?: string): Record<string, string>;
+/**
+ * Rebuild a nested object from dot-delimited keys, parsing each leaf as JSON (falling back to the
+ * raw string). Inverse of {@link flattenKeys}.
+ */
+export declare function deFlattenKeys(entries: Record<string, string>): Record<string, unknown>;
+//# sourceMappingURL=object.d.ts.map

package/dist/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUnH;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,SAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAW7F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAetF"}

package/dist/object.js

@@ -0,0 +1,68 @@
+/** Narrow to a non-array object literal. Excludes arrays and `null`, unlike a bare `typeof === object`. */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Recursively merge `source` into `target`, returning a new object. Nested plain objects merge;
+ * arrays and scalars from `source` replace the target wholesale (a source array overrides, never
+ * extends). Inputs are not mutated.
+ */
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = deepMerge(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Flatten a nested object into dot-delimited keys with JSON-stringified leaf values — e.g.
+ * `{ a: { b: 1 } }` → `{ "a.b": "1" }`. Inverse of {@link deFlattenKeys}.
+ */
+export function flattenKeys(obj, prefix = '') {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (isPlainObject(value)) {
+            Object.assign(result, flattenKeys(value, fullKey));
+        }
+        else {
+            result[fullKey] = JSON.stringify(value);
+        }
+    }
+    return result;
+}
+/**
+ * Rebuild a nested object from dot-delimited keys, parsing each leaf as JSON (falling back to the
+ * raw string). Inverse of {@link flattenKeys}.
+ */
+export function deFlattenKeys(entries) {
+    const result = {};
+    for (const [key, rawValue] of Object.entries(entries)) {
+        const parts = key.split('.');
+        let current = result;
+        for (const part of parts.slice(0, -1)) {
+            if (!isPlainObject(current[part]))
+                current[part] = {};
+            current = current[part];
+        }
+        const last = parts.at(-1);
+        if (last === undefined)
+            continue;
+        current[last] = parseJsonValue(rawValue);
+    }
+    return result;
+}
+/** Parse a string as JSON, returning the original string if it is not valid JSON. */
+function parseJsonValue(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/origin.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Match an origin against a pattern. Supports exact match, the bare `*` (match-all), and a single
+ * `*` wildcard standing for one prefix/suffix gap (e.g. `https://*.example.com`). Patterns with more
+ * than one `*` are NOT glob-expanded — they fall back to exact match (so a multi-wildcard pattern
+ * matches nothing unless it equals the origin verbatim). Keep CORS patterns to a single wildcard.
+ */
 export declare function matchOriginPattern(origin: string, pattern: string): boolean;
 export declare function isAllowedOrigin(origin: string | undefined | null, allowedOrigins: string[]): boolean;
 export declare function getValidatedOrigin(origin: string | undefined | null, allowedOrigins: string[], fallback: string): string;

package/dist/origin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AAAA,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAe3E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAKpG;AAED,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACjC,cAAc,EAAE,MAAM,EAAE,EACxB,QAAQ,EAAE,MAAM,GACjB,MAAM,CAKR"}
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAgB3E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAKpG;AAED,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACjC,cAAc,EAAE,MAAM,EAAE,EACxB,QAAQ,EAAE,MAAM,GACjB,MAAM,CAKR"}

package/dist/origin.js

@@ -1,3 +1,9 @@
+/**
+ * Match an origin against a pattern. Supports exact match, the bare `*` (match-all), and a single
+ * `*` wildcard standing for one prefix/suffix gap (e.g. `https://*.example.com`). Patterns with more
+ * than one `*` are NOT glob-expanded — they fall back to exact match (so a multi-wildcard pattern
+ * matches nothing unless it equals the origin verbatim). Keep CORS patterns to a single wildcard.
+ */
 export function matchOriginPattern(origin, pattern) {
     if (pattern === origin)
         return true;
@@ -6,6 +12,7 @@ export function matchOriginPattern(origin, pattern) {
     if (pattern.includes('*')) {
         const parts = pattern.split('*');
         if (parts.length !== 2) {
+            // More than one `*`: not supported as a glob — exact-match only (see JSDoc).
             return pattern === origin;
         }
         const [prefix, suffix] = parts;

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AASD,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAAiC,GAAG,IAAI,CAErF;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAAiC,GAAG,IAAI,CAE1F;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,MAAM,IAAI,CASxG;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAejD"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAoBD,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAA4D,GAAG,IAAI,CAEhH;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAA4D,GAAG,IAAI,CAErH;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,MAAM,IAAI,CASxG;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAejD"}

package/dist/output.js

@@ -1,12 +1,22 @@
-let defaultStdoutTarget = process.stdout;
-let defaultStderrTarget = process.stderr;
+// Resolved lazily, not at module load: reading `process.std*` eagerly would throw on import in
+// runtimes without `process` (e.g. Cloudflare Workers). `undefined` means "fall back to process".
+let defaultStdoutTarget;
+let defaultStderrTarget;
+function processStream(name) {
+    const proc = globalThis.process;
+    const stream = proc?.[name];
+    if (stream === undefined) {
+        throw new Error(`No ${name} target available: set one via setDefaultOutputTargets or pass an explicit target`);
+    }
+    return stream;
+}
 function writeLine(message, target) {
     target.write(`${message}\n`);
 }
-export function echo(message, target = defaultStdoutTarget) {
+export function echo(message, target = defaultStdoutTarget ?? processStream('stdout')) {
     writeLine(message, target);
 }
-export function echoError(message, target = defaultStderrTarget) {
+export function echoError(message, target = defaultStderrTarget ?? processStream('stderr')) {
     writeLine(message, target);
 }
 export function setDefaultOutputTargets(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-utils",
-    "version": "0.2.8",
+    "version": "0.3.0",
     "description": "Zero-dependency TypeScript utilities for dates, cursors, errors, output, origins, roles, and API responses.",
     "keywords": [
         "typescript",

package/src/api-response.ts

@@ -1,3 +1,5 @@
+import { type AppError, ErrorCode, isAppError } from './errors';
+
 export const API_ERROR_CODES = {
     SUCCESS: 0,
     NOT_FOUND: 404,
@@ -105,3 +107,33 @@ export function conflictResponse(message = 'Resource conflict', details?: unknow
 export function internalErrorResponse(message = 'Internal server error', details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.INTERNAL_ERROR, message, details);
 }
+
+/** Maps each domain {@link ErrorCode} to its HTTP-layer {@link ApiErrorCode}. */
+const ERROR_CODE_TO_HTTP: Record<ErrorCode, ApiErrorCode> = {
+    [ErrorCode.NotFound]: API_ERROR_CODES.NOT_FOUND,
+    [ErrorCode.Validation]: API_ERROR_CODES.VALIDATION_ERROR,
+    [ErrorCode.Conflict]: API_ERROR_CODES.CONFLICT,
+    [ErrorCode.Internal]: API_ERROR_CODES.INTERNAL_ERROR,
+};
+
+// Client-actionable errors whose message is safe to surface. Internal/unknown errors are opaque:
+// their message (and any `cause`) must never reach the client, to avoid leaking implementation detail.
+const CLIENT_SAFE_CODES = new Set<ErrorCode>([ErrorCode.NotFound, ErrorCode.Validation, ErrorCode.Conflict]);
+
+/**
+ * Bridge a thrown error to an API error envelope — the single mapping from the domain error layer
+ * ({@link AppError}) to the wire layer ({@link ApiErrorEnvelope}). Use this in request handlers
+ * instead of hand-mapping `catch` blocks, so HTTP codes stay consistent across endpoints.
+ *
+ * A known {@link AppError} maps to its HTTP code; client-safe codes surface their message, while
+ * `Internal` and any non-`AppError` collapse to an opaque 500 that leaks neither message nor stack.
+ * Pass `details` only when you intend it to reach the client (e.g. validation field errors).
+ */
+export function toApiResponse(error: unknown, details?: unknown): ApiErrorEnvelope {
+    if (isAppError(error)) {
+        const httpCode = ERROR_CODE_TO_HTTP[error.code];
+        const message = CLIENT_SAFE_CODES.has(error.code) ? error.message : 'Internal server error';
+        return errorResponse(httpCode, message, CLIENT_SAFE_CODES.has(error.code) ? details : undefined);
+    }
+    return internalErrorResponse();
+}

package/src/cursor.ts

@@ -6,6 +6,12 @@ export interface CursorData {
     offset?: number;
 }
 
+/**
+ * Upper bound on an encoded cursor. Cursors are short by construction (id + two numbers); a longer
+ * input is hostile (cursors are client-supplied pagination tokens) and is rejected before decode.
+ */
+const MAX_ENCODED_CURSOR_LENGTH = 1024;
+
 export function createCursor(id: string, createdAt?: Date | number, offset?: number): CursorData {
     const cursor: CursorData = { id };
     if (createdAt !== undefined) {
@@ -42,15 +48,11 @@ export function parseCursor(data: string | Record<string, unknown>): CursorData
 }
 
 export function encodeCursor(cursor: CursorData): string {
-    return Buffer.from(JSON.stringify(cursor)).toString('base64url');
+    return base64UrlEncode(JSON.stringify(cursor));
 }
 
 export function decodeCursor(encoded: string): string {
-    try {
-        return Buffer.from(encoded, 'base64url').toString('utf-8');
-    } catch (error) {
-        throw new Error(`Invalid cursor encoding: ${String(error)}`);
-    }
+    return base64UrlDecode(encoded);
 }
 
 export function encodeCursorFromItem(id: string, createdAt?: Date | number, offset?: number): string {
@@ -58,6 +60,9 @@ export function encodeCursorFromItem(id: string, createdAt?: Date | number, offs
 }
 
 export function decodeAndParseCursor(encoded: string): CursorData {
+    if (encoded.length > MAX_ENCODED_CURSOR_LENGTH) {
+        throw new Error('Invalid cursor: exceeds maximum length');
+    }
     return parseCursor(decodeCursor(encoded));
 }
 
@@ -80,3 +85,26 @@ export function buildCursorMeta<T extends { id: string; createdAt?: number | Dat
 
     return meta;
 }
+
+// Web-standard base64url codec via `btoa`/`atob` (available on Node, Bun, and Cloudflare Workers) —
+// avoids node-only `Buffer` so cursors work in every runtime that depends on ts-utils.
+
+function base64UrlEncode(text: string): string {
+    // Encode to UTF-8 bytes first, then to a binary string `btoa` accepts (it only handles latin1).
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+
+function base64UrlDecode(encoded: string): string {
+    const base64 = encoded.replaceAll('-', '+').replaceAll('_', '/');
+    let binary: string;
+    try {
+        binary = atob(base64);
+    } catch {
+        throw new Error('Invalid cursor encoding: not valid base64url');
+    }
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}

package/src/date.ts

@@ -9,7 +9,8 @@ export function toMs(input: Date | number | string | null | undefined): number |
         const parsed = new Date(input).getTime();
         return Number.isNaN(parsed) ? null : parsed;
     }
-    return Math.floor(input);
+    // Reject NaN/±Infinity rather than passing them through as a "valid" timestamp.
+    return Number.isFinite(input) ? Math.floor(input) : null;
 }
 
 export function fromMs(ms: number | null | undefined): Date | null {

package/src/index.ts

@@ -4,5 +4,6 @@ export * from './const';
 export * from './cursor';
 export * from './date';
 export * from './errors';
+export * from './object';
 export * from './origin';
 export * from './output';

package/src/object.ts

@@ -0,0 +1,68 @@
+/** Narrow to a non-array object literal. Excludes arrays and `null`, unlike a bare `typeof === object`. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Recursively merge `source` into `target`, returning a new object. Nested plain objects merge;
+ * arrays and scalars from `source` replace the target wholesale (a source array overrides, never
+ * extends). Inputs are not mutated.
+ */
+export function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = deepMerge(result[key] as Record<string, unknown>, value);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+/**
+ * Flatten a nested object into dot-delimited keys with JSON-stringified leaf values — e.g.
+ * `{ a: { b: 1 } }` → `{ "a.b": "1" }`. Inverse of {@link deFlattenKeys}.
+ */
+export function flattenKeys(obj: Record<string, unknown>, prefix = ''): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (isPlainObject(value)) {
+            Object.assign(result, flattenKeys(value, fullKey));
+        } else {
+            result[fullKey] = JSON.stringify(value);
+        }
+    }
+    return result;
+}
+
+/**
+ * Rebuild a nested object from dot-delimited keys, parsing each leaf as JSON (falling back to the
+ * raw string). Inverse of {@link flattenKeys}.
+ */
+export function deFlattenKeys(entries: Record<string, string>): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, rawValue] of Object.entries(entries)) {
+        const parts = key.split('.');
+        let current = result;
+        for (const part of parts.slice(0, -1)) {
+            if (!isPlainObject(current[part])) current[part] = {};
+            current = current[part] as Record<string, unknown>;
+        }
+
+        const last = parts.at(-1);
+        if (last === undefined) continue;
+        current[last] = parseJsonValue(rawValue);
+    }
+    return result;
+}
+
+/** Parse a string as JSON, returning the original string if it is not valid JSON. */
+function parseJsonValue(value: string): unknown {
+    try {
+        return JSON.parse(value);
+    } catch {
+        return value;
+    }
+}

package/src/origin.ts

@@ -1,3 +1,9 @@
+/**
+ * Match an origin against a pattern. Supports exact match, the bare `*` (match-all), and a single
+ * `*` wildcard standing for one prefix/suffix gap (e.g. `https://*.example.com`). Patterns with more
+ * than one `*` are NOT glob-expanded — they fall back to exact match (so a multi-wildcard pattern
+ * matches nothing unless it equals the origin verbatim). Keep CORS patterns to a single wildcard.
+ */
 export function matchOriginPattern(origin: string, pattern: string): boolean {
     if (pattern === origin) return true;
     if (pattern === '*') return true;
@@ -5,6 +11,7 @@ export function matchOriginPattern(origin: string, pattern: string): boolean {
     if (pattern.includes('*')) {
         const parts = pattern.split('*');
         if (parts.length !== 2) {
+            // More than one `*`: not supported as a glob — exact-match only (see JSDoc).
             return pattern === origin;
         }
         const [prefix, suffix] = parts;

package/src/output.ts

@@ -2,18 +2,29 @@ export interface WriteTarget {
     write(chunk: string): unknown;
 }
 
-let defaultStdoutTarget: WriteTarget = process.stdout;
-let defaultStderrTarget: WriteTarget = process.stderr;
+// Resolved lazily, not at module load: reading `process.std*` eagerly would throw on import in
+// runtimes without `process` (e.g. Cloudflare Workers). `undefined` means "fall back to process".
+let defaultStdoutTarget: WriteTarget | undefined;
+let defaultStderrTarget: WriteTarget | undefined;
+
+function processStream(name: 'stdout' | 'stderr'): WriteTarget {
+    const proc = (globalThis as { process?: { stdout?: WriteTarget; stderr?: WriteTarget } }).process;
+    const stream = proc?.[name];
+    if (stream === undefined) {
+        throw new Error(`No ${name} target available: set one via setDefaultOutputTargets or pass an explicit target`);
+    }
+    return stream;
+}
 
 function writeLine(message: string, target: WriteTarget): void {
     target.write(`${message}\n`);
 }
 
-export function echo(message: string, target: WriteTarget = defaultStdoutTarget): void {
+export function echo(message: string, target: WriteTarget = defaultStdoutTarget ?? processStream('stdout')): void {
     writeLine(message, target);
 }
 
-export function echoError(message: string, target: WriteTarget = defaultStderrTarget): void {
+export function echoError(message: string, target: WriteTarget = defaultStderrTarget ?? processStream('stderr')): void {
     writeLine(message, target);
 }