@gobing-ai/ts-utils 0.3.1 → 0.3.2

package/dist/access.d.ts

@@ -8,5 +8,6 @@
  * rather than forking this module.
  */
 export declare function hasRole(profile: Record<string, unknown> | null | undefined, role: string): boolean;
+/** Collect every role name from a profile — Zitadel IAM roles, `roles` arrays, and object-based role maps — into a deduplicated `string[]`. */
 export declare function getRoles(profile: Record<string, unknown> | null | undefined): string[];
 //# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CA+BlG;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAkCtF"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CA+BlG;AAED,+IAA+I;AAC/I,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAkCtF"}

package/dist/access.js

@@ -39,6 +39,7 @@ export function hasRole(profile, role) {
     }
     return false;
 }
+/** Collect every role name from a profile — Zitadel IAM roles, `roles` arrays, and object-based role maps — into a deduplicated `string[]`. */
 export function getRoles(profile) {
     if (!profile)
         return [];

package/dist/api-response.d.ts

@@ -1,3 +1,4 @@
+/** Standard HTTP/application error codes used in structured API responses. */
 export declare const API_ERROR_CODES: {
     readonly SUCCESS: 0;
     readonly NOT_FOUND: 404;
@@ -8,8 +9,11 @@ export declare const API_ERROR_CODES: {
     readonly CONFLICT: 409;
     readonly INTERNAL_ERROR: 500;
 };
+/** Union of all values in {@link API_ERROR_CODES}. */
 export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+/** Sentiment tag carried in every API envelope. */
 export type ApiEnvelopeResult = 'success' | 'info' | 'warn' | 'error';
+/** Envelope wrapping successful API responses. */
 export interface ApiSuccessEnvelope<T> {
     code: 0;
     message: string;
@@ -21,6 +25,7 @@ export interface ApiSuccessEnvelope<T> {
         offset?: number;
     };
 }
+/** Envelope wrapping failed or problematic API responses. */
 export interface ApiErrorEnvelope {
     result: 'warn' | 'error';
     code: number;
@@ -28,21 +33,37 @@ export interface ApiErrorEnvelope {
     data: null;
     details?: unknown;
 }
+/** Generic API response: either a success envelope or an error envelope. */
 export type ApiEnvelope<T> = ApiSuccessEnvelope<T> | ApiErrorEnvelope;
+/** Build a generic 200-success API envelope. */
 export declare function successResponse<T>(data: T, message?: string): ApiSuccessEnvelope<T>;
+/** Build a 200-success API envelope tagged as informational (`result: "info"`). */
 export declare function infoResponse<T>(data: T, message?: string): ApiSuccessEnvelope<T>;
+/** Build a 200-success envelope for paginated list endpoints, tagging as `info` and attaching pagination `meta`. */
 export declare function paginatedResponse<T>(data: T[], meta: {
     total?: number;
     limit?: number;
     offset?: number;
 }, message?: string): ApiSuccessEnvelope<T[]>;
+/**
+ * Build a structured API error envelope.
+ *
+ * Code ≥ 500 tags `result: "error"`; anything else tags `result: "warn"`.
+ */
 export declare function errorResponse(code: number, message: string, details?: unknown): ApiErrorEnvelope;
+/** Convenience wrapper for a 404 "not found" API error. */
 export declare function notFoundResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+/** Convenience wrapper for a 422 "validation error" API error. */
 export declare function validationErrorResponse(details: unknown, message?: string): ApiErrorEnvelope;
+/** Convenience wrapper for a 400 "bad request" API error. */
 export declare function badRequestResponse(message: string, details?: unknown): ApiErrorEnvelope;
+/** Convenience wrapper for a 401 "unauthorized" API error. */
 export declare function unauthorizedResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+/** Convenience wrapper for a 403 "forbidden" API error. */
 export declare function forbiddenResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+/** Convenience wrapper for a 409 "conflict" API error. */
 export declare function conflictResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+/** Convenience wrapper for a 500 "internal server error" API error. */
 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

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

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

package/dist/api-response.js

@@ -1,4 +1,5 @@
 import { ErrorCode, isAppError } from './errors.js';
+/** Standard HTTP/application error codes used in structured API responses. */
 export const API_ERROR_CODES = {
     SUCCESS: 0,
     NOT_FOUND: 404,
@@ -9,6 +10,7 @@ export const API_ERROR_CODES = {
     CONFLICT: 409,
     INTERNAL_ERROR: 500,
 };
+/** Build a generic 200-success API envelope. */
 export function successResponse(data, message = 'Success') {
     return {
         code: API_ERROR_CODES.SUCCESS,
@@ -17,6 +19,7 @@ export function successResponse(data, message = 'Success') {
         data,
     };
 }
+/** Build a 200-success API envelope tagged as informational (`result: "info"`). */
 export function infoResponse(data, message = 'Data retrieved successfully') {
     return {
         code: API_ERROR_CODES.SUCCESS,
@@ -25,6 +28,7 @@ export function infoResponse(data, message = 'Data retrieved successfully') {
         data,
     };
 }
+/** Build a 200-success envelope for paginated list endpoints, tagging as `info` and attaching pagination `meta`. */
 export function paginatedResponse(data, meta, message = 'Data retrieved successfully') {
     return {
         code: API_ERROR_CODES.SUCCESS,
@@ -34,6 +38,11 @@ export function paginatedResponse(data, meta, message = 'Data retrieved successf
         meta,
     };
 }
+/**
+ * Build a structured API error envelope.
+ *
+ * Code ≥ 500 tags `result: "error"`; anything else tags `result: "warn"`.
+ */
 export function errorResponse(code, message, details) {
     const response = {
         code,
@@ -46,24 +55,31 @@ export function errorResponse(code, message, details) {
     }
     return response;
 }
+/** Convenience wrapper for a 404 "not found" API error. */
 export function notFoundResponse(message = 'Resource not found', details) {
     return errorResponse(API_ERROR_CODES.NOT_FOUND, message, details);
 }
+/** Convenience wrapper for a 422 "validation error" API error. */
 export function validationErrorResponse(details, message = 'Validation failed') {
     return errorResponse(API_ERROR_CODES.VALIDATION_ERROR, message, details);
 }
+/** Convenience wrapper for a 400 "bad request" API error. */
 export function badRequestResponse(message, details) {
     return errorResponse(API_ERROR_CODES.BAD_REQUEST, message, details);
 }
+/** Convenience wrapper for a 401 "unauthorized" API error. */
 export function unauthorizedResponse(message = 'Authentication required', details) {
     return errorResponse(API_ERROR_CODES.UNAUTHORIZED, message, details);
 }
+/** Convenience wrapper for a 403 "forbidden" API error. */
 export function forbiddenResponse(message = 'Access forbidden', details) {
     return errorResponse(API_ERROR_CODES.FORBIDDEN, message, details);
 }
+/** Convenience wrapper for a 409 "conflict" API error. */
 export function conflictResponse(message = 'Resource conflict', details) {
     return errorResponse(API_ERROR_CODES.CONFLICT, message, details);
 }
+/** Convenience wrapper for a 500 "internal server error" API error. */
 export function internalErrorResponse(message = 'Internal server error', details) {
     return errorResponse(API_ERROR_CODES.INTERNAL_ERROR, message, details);
 }

package/dist/const.d.ts

@@ -1,3 +1,5 @@
+/** Log category identifier for application-level messages. */
 export declare const LOG_CATEGORY_APP = "app";
+/** Log category identifier for CLI-level messages. */
 export declare const LOG_CATEGORY_CLI = "cli";
 //# sourceMappingURL=const.d.ts.map

package/dist/const.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../src/const.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,eAAO,MAAM,gBAAgB,QAAQ,CAAC"}
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../src/const.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,QAAQ,CAAC"}

package/dist/const.js

@@ -1,2 +1,4 @@
+/** Log category identifier for application-level messages. */
 export const LOG_CATEGORY_APP = 'app';
+/** Log category identifier for CLI-level messages. */
 export const LOG_CATEGORY_CLI = 'cli';

package/dist/cursor.d.ts

@@ -1,14 +1,22 @@
+/** Data embedded in a cursor-based pagination token. */
 export interface CursorData {
     id: string;
     createdAt?: number;
     offset?: number;
 }
+/** Build a {@link CursorData} record from raw fields. */
 export declare function createCursor(id: string, createdAt?: Date | number, offset?: number): CursorData;
+/** Parse a raw cursor payload (JSON string or parsed object) into validated {@link CursorData}. */
 export declare function parseCursor(data: string | Record<string, unknown>): CursorData;
+/** Encode {@link CursorData} into an opaque base64url cursor string. */
 export declare function encodeCursor(cursor: CursorData): string;
+/** Decode a base64url cursor string back to its JSON representation. */
 export declare function decodeCursor(encoded: string): string;
+/** One-shot: create a cursor from item fields and encode it immediately. */
 export declare function encodeCursorFromItem(id: string, createdAt?: Date | number, offset?: number): string;
+/** Decode a base64url cursor string and parse it into validated {@link CursorData}. Enforces a size cap to reject hostile input. */
 export declare function decodeAndParseCursor(encoded: string): CursorData;
+/** Generate pagination metadata (`nextCursor`, `hasMore`, `limit`) for a list result. Uses the last item's `id` and `createdAt` as the cursor anchor. */
 export declare function buildCursorMeta<T extends {
     id: string;
     createdAt?: number | Date;

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;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"}
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAY/F;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAmB9E;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEvD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED,oIAAoI;AACpI,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAKhE;AAED,yJAAyJ;AACzJ,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

@@ -4,6 +4,7 @@ import { toMs } from './date.js';
  * input is hostile (cursors are client-supplied pagination tokens) and is rejected before decode.
  */
 const MAX_ENCODED_CURSOR_LENGTH = 1024;
+/** Build a {@link CursorData} record from raw fields. */
 export function createCursor(id, createdAt, offset) {
     const cursor = { id };
     if (createdAt !== undefined) {
@@ -17,6 +18,7 @@ export function createCursor(id, createdAt, offset) {
     }
     return cursor;
 }
+/** Parse a raw cursor payload (JSON string or parsed object) into validated {@link CursorData}. */
 export function parseCursor(data) {
     const parsed = typeof data === 'string' ? JSON.parse(data) : data;
     if (!parsed || typeof parsed !== 'object') {
@@ -34,21 +36,26 @@ export function parseCursor(data) {
     }
     return result;
 }
+/** Encode {@link CursorData} into an opaque base64url cursor string. */
 export function encodeCursor(cursor) {
     return base64UrlEncode(JSON.stringify(cursor));
 }
+/** Decode a base64url cursor string back to its JSON representation. */
 export function decodeCursor(encoded) {
     return base64UrlDecode(encoded);
 }
+/** One-shot: create a cursor from item fields and encode it immediately. */
 export function encodeCursorFromItem(id, createdAt, offset) {
     return encodeCursor(createCursor(id, createdAt, offset));
 }
+/** Decode a base64url cursor string and parse it into validated {@link CursorData}. Enforces a size cap to reject hostile input. */
 export function decodeAndParseCursor(encoded) {
     if (encoded.length > MAX_ENCODED_CURSOR_LENGTH) {
         throw new Error('Invalid cursor: exceeds maximum length');
     }
     return parseCursor(decodeCursor(encoded));
 }
+/** Generate pagination metadata (`nextCursor`, `hasMore`, `limit`) for a list result. Uses the last item's `id` and `createdAt` as the cursor anchor. */
 export function buildCursorMeta(items, limit, hasMore) {
     const meta = {
         hasMore,

package/dist/date.d.ts

@@ -1,4 +1,7 @@
+/** Current time in milliseconds since the Unix epoch. */
 export declare function nowMs(): number;
+/** Normalize a date/time input to milliseconds since the Unix epoch. Returns `null` for unparseable or invalid values. */
 export declare function toMs(input: Date | number | string | null | undefined): number | null;
+/** Convert a millisecond timestamp to a `Date`. Returns `null` for `null`, `undefined`, or `NaN`. */
 export declare function fromMs(ms: number | null | undefined): Date | null;
 //# sourceMappingURL=date.d.ts.map

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,CASpF;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,yDAAyD;AACzD,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,0HAA0H;AAC1H,wBAAgB,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CASpF;AAED,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAGjE"}

package/dist/date.js

@@ -1,6 +1,8 @@
+/** Current time in milliseconds since the Unix epoch. */
 export function nowMs() {
     return Date.now();
 }
+/** Normalize a date/time input to milliseconds since the Unix epoch. Returns `null` for unparseable or invalid values. */
 export function toMs(input) {
     if (input === null || input === undefined)
         return null;
@@ -13,6 +15,7 @@ export function toMs(input) {
     // Reject NaN/±Infinity rather than passing them through as a "valid" timestamp.
     return Number.isFinite(input) ? Math.floor(input) : null;
 }
+/** Convert a millisecond timestamp to a `Date`. Returns `null` for `null`, `undefined`, or `NaN`. */
 export function fromMs(ms) {
     if (ms === null || ms === undefined || Number.isNaN(ms))
         return null;

package/dist/errors.d.ts

@@ -1,26 +1,34 @@
+/** Canonical domain-error codes carried by every {@link AppError}. */
 export declare const ErrorCode: {
     readonly NotFound: "NOT_FOUND";
     readonly Validation: "VALIDATION";
     readonly Conflict: "CONFLICT";
     readonly Internal: "INTERNAL";
 };
+/** Union of all values in the {@link ErrorCode} const object. */
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Base application error: holds a machine-readable {@link ErrorCode} `code`. */
 export declare class AppError extends Error {
     readonly code: ErrorCode;
     constructor(code: ErrorCode, message: string);
 }
+/** Specialized {@link AppError} for "not found" scenarios. Carries `ErrorCode.NotFound`. */
 export declare class NotFoundError extends AppError {
     constructor(message: string);
 }
+/** Specialized {@link AppError} for validation failures. Carries `ErrorCode.Validation`. */
 export declare class ValidationError extends AppError {
     constructor(message: string);
 }
+/** Specialized {@link AppError} for resource conflicts. Carries `ErrorCode.Conflict`. */
 export declare class ConflictError extends AppError {
     constructor(message: string);
 }
+/** Specialized {@link AppError} for unexpected internal failures. Carries `ErrorCode.Internal` and an optional root `cause`. */
 export declare class InternalError extends AppError {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
+/** Type guard: narrows an unknown error value to {@link AppError}. */
 export declare function isAppError(error: unknown): error is AppError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE,qBAAa,QAAS,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;gBAEb,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAK/C;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,eAAgB,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;aAGjB,KAAK,CAAC,EAAE,OAAO;gBADjC,OAAO,EAAE,MAAM,EACG,KAAK,CAAC,EAAE,OAAO,YAAA;CAKxC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE,iFAAiF;AACjF,qBAAa,QAAS,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;gBAEb,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAK/C;AAED,4FAA4F;AAC5F,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED,4FAA4F;AAC5F,qBAAa,eAAgB,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAI9B;AAED,yFAAyF;AACzF,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED,gIAAgI;AAChI,qBAAa,aAAc,SAAQ,QAAQ;aAGjB,KAAK,CAAC,EAAE,OAAO;gBADjC,OAAO,EAAE,MAAM,EACG,KAAK,CAAC,EAAE,OAAO,YAAA;CAKxC;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}

package/dist/errors.js

@@ -1,9 +1,11 @@
+/** Canonical domain-error codes carried by every {@link AppError}. */
 export const ErrorCode = {
     NotFound: 'NOT_FOUND',
     Validation: 'VALIDATION',
     Conflict: 'CONFLICT',
     Internal: 'INTERNAL',
 };
+/** Base application error: holds a machine-readable {@link ErrorCode} `code`. */
 export class AppError extends Error {
     code;
     constructor(code, message) {
@@ -12,24 +14,28 @@ export class AppError extends Error {
         this.code = code;
     }
 }
+/** Specialized {@link AppError} for "not found" scenarios. Carries `ErrorCode.NotFound`. */
 export class NotFoundError extends AppError {
     constructor(message) {
         super(ErrorCode.NotFound, message);
         this.name = 'NotFoundError';
     }
 }
+/** Specialized {@link AppError} for validation failures. Carries `ErrorCode.Validation`. */
 export class ValidationError extends AppError {
     constructor(message) {
         super(ErrorCode.Validation, message);
         this.name = 'ValidationError';
     }
 }
+/** Specialized {@link AppError} for resource conflicts. Carries `ErrorCode.Conflict`. */
 export class ConflictError extends AppError {
     constructor(message) {
         super(ErrorCode.Conflict, message);
         this.name = 'ConflictError';
     }
 }
+/** Specialized {@link AppError} for unexpected internal failures. Carries `ErrorCode.Internal` and an optional root `cause`. */
 export class InternalError extends AppError {
     cause;
     constructor(message, cause) {
@@ -38,6 +44,7 @@ export class InternalError extends AppError {
         this.name = 'InternalError';
     }
 }
+/** Type guard: narrows an unknown error value to {@link AppError}. */
 export function isAppError(error) {
     return error instanceof AppError;
 }

package/dist/origin.d.ts

@@ -5,6 +5,8 @@
  * matches nothing unless it equals the origin verbatim). Keep CORS patterns to a single wildcard.
  */
 export declare function matchOriginPattern(origin: string, pattern: string): boolean;
+/** Check whether a request origin matches any entry in an allowlist. Delegates to {@link matchOriginPattern} per entry. */
 export declare function isAllowedOrigin(origin: string | undefined | null, allowedOrigins: string[]): boolean;
+/** Return the request origin if it is in the allowlist; otherwise return a safe `fallback` origin. */
 export declare function getValidatedOrigin(origin: string | undefined | null, allowedOrigins: string[], fallback: string): string;
 //# sourceMappingURL=origin.d.ts.map

package/dist/origin.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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,2HAA2H;AAC3H,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAKpG;AAED,sGAAsG;AACtG,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

@@ -22,6 +22,7 @@ export function matchOriginPattern(origin, pattern) {
     }
     return false;
 }
+/** Check whether a request origin matches any entry in an allowlist. Delegates to {@link matchOriginPattern} per entry. */
 export function isAllowedOrigin(origin, allowedOrigins) {
     if (!origin)
         return false;
@@ -29,6 +30,7 @@ export function isAllowedOrigin(origin, allowedOrigins) {
         return false;
     return allowedOrigins.some((pattern) => matchOriginPattern(origin, pattern));
 }
+/** Return the request origin if it is in the allowlist; otherwise return a safe `fallback` origin. */
 export function getValidatedOrigin(origin, allowedOrigins, fallback) {
     if (origin && isAllowedOrigin(origin, allowedOrigins)) {
         return origin;

package/dist/output.d.ts

@@ -1,16 +1,26 @@
+/** Minimal write sink: anything that accepts a string chunk. */
 export interface WriteTarget {
     write(chunk: string): unknown;
 }
+/** Write a line to a target, defaulting to stdout. */
 export declare function echo(message: string, target?: WriteTarget): void;
+/** Write a line to a target, defaulting to stderr. */
 export declare function echoError(message: string, target?: WriteTarget): void;
+/**
+ * Override the default stdout/stderr targets.
+ *
+ * Returns a rollback function that restores the previous targets.
+ */
 export declare function setDefaultOutputTargets(opts: {
     stdout?: WriteTarget;
     stderr?: WriteTarget;
 }): () => void;
+/** In-memory `WriteTarget` that records all chunks for later retrieval. */
 export interface BufferTarget extends WriteTarget {
     readonly chunks: string[];
     text(): string;
     clear(): void;
 }
+/** Create an in-memory {@link BufferTarget} for capturing output during tests or tooling. */
 export declare function createBufferTarget(): BufferTarget;
 //# sourceMappingURL=output.d.ts.map

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;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"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,WAAW,WAAW;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAoBD,sDAAsD;AACtD,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAA4D,GAAG,IAAI,CAEhH;AAED,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAA4D,GAAG,IAAI,CAErH;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,MAAM,IAAI,CASxG;AAED,2EAA2E;AAC3E,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,6FAA6F;AAC7F,wBAAgB,kBAAkB,IAAI,YAAY,CAejD"}

package/dist/output.js

@@ -13,12 +13,19 @@ function processStream(name) {
 function writeLine(message, target) {
     target.write(`${message}\n`);
 }
+/** Write a line to a target, defaulting to stdout. */
 export function echo(message, target = defaultStdoutTarget ?? processStream('stdout')) {
     writeLine(message, target);
 }
+/** Write a line to a target, defaulting to stderr. */
 export function echoError(message, target = defaultStderrTarget ?? processStream('stderr')) {
     writeLine(message, target);
 }
+/**
+ * Override the default stdout/stderr targets.
+ *
+ * Returns a rollback function that restores the previous targets.
+ */
 export function setDefaultOutputTargets(opts) {
     const prevStdout = defaultStdoutTarget;
     const prevStderr = defaultStderrTarget;
@@ -31,6 +38,7 @@ export function setDefaultOutputTargets(opts) {
         defaultStderrTarget = prevStderr;
     };
 }
+/** Create an in-memory {@link BufferTarget} for capturing output during tests or tooling. */
 export function createBufferTarget() {
     const chunks = [];
     return {

package/package.json

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

package/src/access.ts

@@ -40,6 +40,7 @@ export function hasRole(profile: Record<string, unknown> | null | undefined, rol
     return false;
 }
 
+/** Collect every role name from a profile — Zitadel IAM roles, `roles` arrays, and object-based role maps — into a deduplicated `string[]`. */
 export function getRoles(profile: Record<string, unknown> | null | undefined): string[] {
     if (!profile) return [];
 

package/src/api-response.ts

@@ -1,5 +1,6 @@
 import { type AppError, ErrorCode, isAppError } from './errors';
 
+/** Standard HTTP/application error codes used in structured API responses. */
 export const API_ERROR_CODES = {
     SUCCESS: 0,
     NOT_FOUND: 404,
@@ -11,10 +12,13 @@ export const API_ERROR_CODES = {
     INTERNAL_ERROR: 500,
 } as const;
 
+/** Union of all values in {@link API_ERROR_CODES}. */
 export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
 
+/** Sentiment tag carried in every API envelope. */
 export type ApiEnvelopeResult = 'success' | 'info' | 'warn' | 'error';
 
+/** Envelope wrapping successful API responses. */
 export interface ApiSuccessEnvelope<T> {
     code: 0;
     message: string;
@@ -23,6 +27,7 @@ export interface ApiSuccessEnvelope<T> {
     meta?: { total?: number; limit?: number; offset?: number };
 }
 
+/** Envelope wrapping failed or problematic API responses. */
 export interface ApiErrorEnvelope {
     result: 'warn' | 'error';
     code: number;
@@ -31,8 +36,10 @@ export interface ApiErrorEnvelope {
     details?: unknown;
 }
 
+/** Generic API response: either a success envelope or an error envelope. */
 export type ApiEnvelope<T> = ApiSuccessEnvelope<T> | ApiErrorEnvelope;
 
+/** Build a generic 200-success API envelope. */
 export function successResponse<T>(data: T, message = 'Success'): ApiSuccessEnvelope<T> {
     return {
         code: API_ERROR_CODES.SUCCESS,
@@ -42,6 +49,7 @@ export function successResponse<T>(data: T, message = 'Success'): ApiSuccessEnve
     };
 }
 
+/** Build a 200-success API envelope tagged as informational (`result: "info"`). */
 export function infoResponse<T>(data: T, message = 'Data retrieved successfully'): ApiSuccessEnvelope<T> {
     return {
         code: API_ERROR_CODES.SUCCESS,
@@ -51,6 +59,7 @@ export function infoResponse<T>(data: T, message = 'Data retrieved successfully'
     };
 }
 
+/** Build a 200-success envelope for paginated list endpoints, tagging as `info` and attaching pagination `meta`. */
 export function paginatedResponse<T>(
     data: T[],
     meta: { total?: number; limit?: number; offset?: number },
@@ -65,6 +74,11 @@ export function paginatedResponse<T>(
     };
 }
 
+/**
+ * Build a structured API error envelope.
+ *
+ * Code ≥ 500 tags `result: "error"`; anything else tags `result: "warn"`.
+ */
 export function errorResponse(code: number, message: string, details?: unknown): ApiErrorEnvelope {
     const response: ApiErrorEnvelope = {
         code,
@@ -80,30 +94,37 @@ export function errorResponse(code: number, message: string, details?: unknown):
     return response;
 }
 
+/** Convenience wrapper for a 404 "not found" API error. */
 export function notFoundResponse(message = 'Resource not found', details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.NOT_FOUND, message, details);
 }
 
+/** Convenience wrapper for a 422 "validation error" API error. */
 export function validationErrorResponse(details: unknown, message = 'Validation failed'): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.VALIDATION_ERROR, message, details);
 }
 
+/** Convenience wrapper for a 400 "bad request" API error. */
 export function badRequestResponse(message: string, details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.BAD_REQUEST, message, details);
 }
 
+/** Convenience wrapper for a 401 "unauthorized" API error. */
 export function unauthorizedResponse(message = 'Authentication required', details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.UNAUTHORIZED, message, details);
 }
 
+/** Convenience wrapper for a 403 "forbidden" API error. */
 export function forbiddenResponse(message = 'Access forbidden', details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.FORBIDDEN, message, details);
 }
 
+/** Convenience wrapper for a 409 "conflict" API error. */
 export function conflictResponse(message = 'Resource conflict', details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.CONFLICT, message, details);
 }
 
+/** Convenience wrapper for a 500 "internal server error" API error. */
 export function internalErrorResponse(message = 'Internal server error', details?: unknown): ApiErrorEnvelope {
     return errorResponse(API_ERROR_CODES.INTERNAL_ERROR, message, details);
 }

package/src/const.ts

@@ -1,3 +1,5 @@
+/** Log category identifier for application-level messages. */
 export const LOG_CATEGORY_APP = 'app';
 
+/** Log category identifier for CLI-level messages. */
 export const LOG_CATEGORY_CLI = 'cli';

package/src/cursor.ts

@@ -1,5 +1,6 @@
 import { toMs } from './date';
 
+/** Data embedded in a cursor-based pagination token. */
 export interface CursorData {
     id: string;
     createdAt?: number;
@@ -12,6 +13,7 @@ export interface CursorData {
  */
 const MAX_ENCODED_CURSOR_LENGTH = 1024;
 
+/** Build a {@link CursorData} record from raw fields. */
 export function createCursor(id: string, createdAt?: Date | number, offset?: number): CursorData {
     const cursor: CursorData = { id };
     if (createdAt !== undefined) {
@@ -26,6 +28,7 @@ export function createCursor(id: string, createdAt?: Date | number, offset?: num
     return cursor;
 }
 
+/** Parse a raw cursor payload (JSON string or parsed object) into validated {@link CursorData}. */
 export function parseCursor(data: string | Record<string, unknown>): CursorData {
     const parsed = typeof data === 'string' ? (JSON.parse(data) as Record<string, unknown>) : data;
 
@@ -47,18 +50,22 @@ export function parseCursor(data: string | Record<string, unknown>): CursorData
     return result;
 }
 
+/** Encode {@link CursorData} into an opaque base64url cursor string. */
 export function encodeCursor(cursor: CursorData): string {
     return base64UrlEncode(JSON.stringify(cursor));
 }
 
+/** Decode a base64url cursor string back to its JSON representation. */
 export function decodeCursor(encoded: string): string {
     return base64UrlDecode(encoded);
 }
 
+/** One-shot: create a cursor from item fields and encode it immediately. */
 export function encodeCursorFromItem(id: string, createdAt?: Date | number, offset?: number): string {
     return encodeCursor(createCursor(id, createdAt, offset));
 }
 
+/** Decode a base64url cursor string and parse it into validated {@link CursorData}. Enforces a size cap to reject hostile input. */
 export function decodeAndParseCursor(encoded: string): CursorData {
     if (encoded.length > MAX_ENCODED_CURSOR_LENGTH) {
         throw new Error('Invalid cursor: exceeds maximum length');
@@ -66,6 +73,7 @@ export function decodeAndParseCursor(encoded: string): CursorData {
     return parseCursor(decodeCursor(encoded));
 }
 
+/** Generate pagination metadata (`nextCursor`, `hasMore`, `limit`) for a list result. Uses the last item's `id` and `createdAt` as the cursor anchor. */
 export function buildCursorMeta<T extends { id: string; createdAt?: number | Date }>(
     items: T[],
     limit: number,

package/src/date.ts

@@ -1,7 +1,9 @@
+/** Current time in milliseconds since the Unix epoch. */
 export function nowMs(): number {
     return Date.now();
 }
 
+/** Normalize a date/time input to milliseconds since the Unix epoch. Returns `null` for unparseable or invalid values. */
 export function toMs(input: Date | number | string | null | undefined): number | null {
     if (input === null || input === undefined) return null;
     if (input instanceof Date) return input.getTime();
@@ -13,6 +15,7 @@ export function toMs(input: Date | number | string | null | undefined): number |
     return Number.isFinite(input) ? Math.floor(input) : null;
 }
 
+/** Convert a millisecond timestamp to a `Date`. Returns `null` for `null`, `undefined`, or `NaN`. */
 export function fromMs(ms: number | null | undefined): Date | null {
     if (ms === null || ms === undefined || Number.isNaN(ms)) return null;
     return new Date(ms);

package/src/errors.ts

@@ -1,3 +1,4 @@
+/** Canonical domain-error codes carried by every {@link AppError}. */
 export const ErrorCode = {
     NotFound: 'NOT_FOUND',
     Validation: 'VALIDATION',
@@ -5,8 +6,10 @@ export const ErrorCode = {
     Internal: 'INTERNAL',
 } as const;
 
+/** Union of all values in the {@link ErrorCode} const object. */
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 
+/** Base application error: holds a machine-readable {@link ErrorCode} `code`. */
 export class AppError extends Error {
     readonly code: ErrorCode;
 
@@ -17,6 +20,7 @@ export class AppError extends Error {
     }
 }
 
+/** Specialized {@link AppError} for "not found" scenarios. Carries `ErrorCode.NotFound`. */
 export class NotFoundError extends AppError {
     constructor(message: string) {
         super(ErrorCode.NotFound, message);
@@ -24,6 +28,7 @@ export class NotFoundError extends AppError {
     }
 }
 
+/** Specialized {@link AppError} for validation failures. Carries `ErrorCode.Validation`. */
 export class ValidationError extends AppError {
     constructor(message: string) {
         super(ErrorCode.Validation, message);
@@ -31,6 +36,7 @@ export class ValidationError extends AppError {
     }
 }
 
+/** Specialized {@link AppError} for resource conflicts. Carries `ErrorCode.Conflict`. */
 export class ConflictError extends AppError {
     constructor(message: string) {
         super(ErrorCode.Conflict, message);
@@ -38,6 +44,7 @@ export class ConflictError extends AppError {
     }
 }
 
+/** Specialized {@link AppError} for unexpected internal failures. Carries `ErrorCode.Internal` and an optional root `cause`. */
 export class InternalError extends AppError {
     constructor(
         message: string,
@@ -48,6 +55,7 @@ export class InternalError extends AppError {
     }
 }
 
+/** Type guard: narrows an unknown error value to {@link AppError}. */
 export function isAppError(error: unknown): error is AppError {
     return error instanceof AppError;
 }

package/src/origin.ts

@@ -22,6 +22,7 @@ export function matchOriginPattern(origin: string, pattern: string): boolean {
     return false;
 }
 
+/** Check whether a request origin matches any entry in an allowlist. Delegates to {@link matchOriginPattern} per entry. */
 export function isAllowedOrigin(origin: string | undefined | null, allowedOrigins: string[]): boolean {
     if (!origin) return false;
     if (!allowedOrigins || allowedOrigins.length === 0) return false;
@@ -29,6 +30,7 @@ export function isAllowedOrigin(origin: string | undefined | null, allowedOrigin
     return allowedOrigins.some((pattern) => matchOriginPattern(origin, pattern));
 }
 
+/** Return the request origin if it is in the allowlist; otherwise return a safe `fallback` origin. */
 export function getValidatedOrigin(
     origin: string | undefined | null,
     allowedOrigins: string[],

package/src/output.ts

@@ -1,3 +1,4 @@
+/** Minimal write sink: anything that accepts a string chunk. */
 export interface WriteTarget {
     write(chunk: string): unknown;
 }
@@ -20,14 +21,21 @@ function writeLine(message: string, target: WriteTarget): void {
     target.write(`${message}\n`);
 }
 
+/** Write a line to a target, defaulting to stdout. */
 export function echo(message: string, target: WriteTarget = defaultStdoutTarget ?? processStream('stdout')): void {
     writeLine(message, target);
 }
 
+/** Write a line to a target, defaulting to stderr. */
 export function echoError(message: string, target: WriteTarget = defaultStderrTarget ?? processStream('stderr')): void {
     writeLine(message, target);
 }
 
+/**
+ * Override the default stdout/stderr targets.
+ *
+ * Returns a rollback function that restores the previous targets.
+ */
 export function setDefaultOutputTargets(opts: { stdout?: WriteTarget; stderr?: WriteTarget }): () => void {
     const prevStdout = defaultStdoutTarget;
     const prevStderr = defaultStderrTarget;
@@ -39,12 +47,14 @@ export function setDefaultOutputTargets(opts: { stdout?: WriteTarget; stderr?: W
     };
 }
 
+/** In-memory `WriteTarget` that records all chunks for later retrieval. */
 export interface BufferTarget extends WriteTarget {
     readonly chunks: string[];
     text(): string;
     clear(): void;
 }
 
+/** Create an in-memory {@link BufferTarget} for capturing output during tests or tooling. */
 export function createBufferTarget(): BufferTarget {
     const chunks: string[] = [];
     return {