@pencroff-lab/kore 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,228 @@
+# @pencroff-lab/kore
+
+TypeScript core utilities library providing value-based error handling types inspired by Go-style error handling. Published as a dual ESM/CJS package.
+
+## Install
+
+```bash
+npm install @pencroff-lab/kore
+# or
+bun add @pencroff-lab/kore
+```
+
+Requires TypeScript 5.9+ as a peer dependency.
+
+## Documentation
+
+Detailed API documentation for each module:
+
+- [Err](docs/err.md) -- Immutable, value-based error type with wrapping, aggregation, and serialization
+- [Outcome\<T\>](docs/outcome.md) -- Monadic container for type-safe error handling with tuple-first API
+- [dtStamp](docs/format_dt.md) -- Filesystem/log-safe date formatting utility
+
+## API
+
+### Err
+
+Immutable, value-based error type. Supports wrapping (cause chains), aggregation (multiple errors), hierarchical error codes, JSON serialization, and conversion to native `Error`.
+
+```typescript
+import { Err } from "@pencroff-lab/kore";
+
+// Create an error with a code
+const err = Err.from("User not found", "NOT_FOUND");
+
+// Wrap with context (returns a new instance)
+const wrapped = err.wrap("Failed to load profile");
+
+// Aggregate multiple errors
+let errors = Err.aggregate("Validation failed");
+errors = errors.add("Name is required");
+errors = errors.add(Err.from("Invalid email", "INVALID_EMAIL"));
+
+if (errors.count > 0) {
+  console.log(errors.toString());
+}
+```
+
+#### Creating errors
+
+```typescript
+// From string with code
+Err.from("Timeout", "TIMEOUT");
+
+// From string with options
+Err.from("Connection failed", {
+  code: "DB_ERROR",
+  metadata: { host: "localhost" },
+});
+
+// From native Error (preserves stack and cause chain)
+try {
+  riskyOperation();
+} catch (e) {
+  Err.from(e as Error, { code: "OPERATION_FAILED" });
+}
+
+// Static wrap for catch blocks
+try {
+  await db.query(sql);
+} catch (e) {
+  Err.wrap("Database query failed", e as Error);
+}
+```
+
+#### Error inspection
+
+```typescript
+const err = Err.from("DB error", "DB:CONNECTION:TIMEOUT")
+  .wrap("Repository failed")
+  .wrap("Service unavailable");
+
+err.hasCode("DB:CONNECTION:TIMEOUT"); // true - exact match in chain
+err.hasCodePrefix("DB"); // true - hierarchical prefix match
+err.root.message; // "DB error" - original error
+err.chain(); // array from root to current
+err.find((e) => e.code === "DB:CONNECTION:TIMEOUT"); // find in tree
+```
+
+#### Serialization
+
+```typescript
+// Serialize for API responses
+const json = err.toJSON({ stack: false }); // omit stack for public APIs
+
+// Deserialize
+const restored = Err.fromJSON(json);
+
+// Convert to native Error
+throw err.toError();
+```
+
+### Outcome\<T\>
+
+Monadic container wrapping `ResultTuple<T>` (`[T, null] | [null, Err]`). Supports `map`/`mapErr`/`pipe`/`pipeAsync` chains, combinators (`all`, `any`), side effects (`effect`), and terminal operations (`toTuple`, `defaultTo`, `either`).
+
+```typescript
+import { Outcome, Err } from "@pencroff-lab/kore";
+
+// Create from callback
+const outcome = Outcome.from(() => {
+  if (!isValid(input)) return Err.from("Invalid input", "VALIDATION");
+  return [processedValue, null];
+});
+
+// Extract with tuple destructuring
+const [value, err] = outcome.toTuple();
+if (err) {
+  console.error(err.message);
+  return;
+}
+console.log(value);
+```
+
+#### Construction
+
+```typescript
+Outcome.ok(42); // success
+Outcome.err("Failed", "ERROR_CODE"); // error
+Outcome.unit(); // void success (null value)
+
+// From sync callback (catches throws)
+Outcome.from(() => {
+  const data = JSON.parse(input); // may throw
+  return [data, null];
+});
+
+// From async callback
+await Outcome.fromAsync(async () => {
+  const res = await fetch("/api/data");
+  if (!res.ok) return Err.from("Request failed", "HTTP_ERROR");
+  return [await res.json(), null];
+});
+```
+
+#### Transformations
+
+```typescript
+const result = Outcome.ok(5)
+  .map((n) => [n * 2, null]) // transform success
+  .mapErr((err) => err.wrap("Added context")) // transform error
+  .toTuple();
+
+// Pipe for sequential transformations with access to both value and error
+const piped = Outcome.ok(rawInput).pipe(
+  ([val, err]) => {
+    if (err) return err;
+    return [validate(val), null];
+  },
+  ([val, err]) => {
+    if (err) return err;
+    return [transform(val), null];
+  },
+);
+```
+
+#### Combinators
+
+```typescript
+// All must succeed (collects all errors)
+const all = Outcome.all([Outcome.ok(1), Outcome.ok(2), Outcome.ok(3)]);
+// all.value === [1, 2, 3]
+
+// First success wins
+const any = Outcome.any([
+  Outcome.err("Failed"),
+  Outcome.ok(42),
+  Outcome.ok(100),
+]);
+// any.value === 42
+```
+
+#### Terminal operations
+
+```typescript
+// Default value on error
+const count = parseNumber(input).defaultTo(0);
+
+// Computed fallback
+const name = fetchUser(id).defaultTo((err) =>
+  err.hasCode("NOT_FOUND") ? "Guest" : "Unknown",
+);
+
+// Transform both cases
+const response = processOrder(orderId).either(
+  (order) => ({ status: 200, body: order }),
+  (err) => ({ status: err.hasCode("NOT_FOUND") ? 404 : 500, body: { error: err.message } }),
+);
+```
+
+### Utilities
+
+#### dtStamp
+
+Formats a `Date` into a compact timestamp string. Useful for filenames, logs, and identifiers.
+
+```typescript
+import { dtStamp } from "@pencroff-lab/kore";
+
+dtStamp(); // "20260218_153045"
+dtStamp(new Date(), { parts: "date" }); // "20260218"
+dtStamp(new Date(), { parts: "time", ms: true }); // "153045_123"
+dtStamp(new Date(), { compact: true }); // "20260218153045"
+dtStamp(new Date(), { tz: "local" }); // uses local timezone
+```
+
+## Development
+
+```bash
+bun install                # install dependencies
+bun test                   # run tests
+bun run test:coverage      # run tests with coverage (>= 83%)
+bun run lint               # lint + type check (auto-fix)
+bun run build              # build ESM + CJS to dist/
+```
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/cjs/src/utils/format_dt.d.ts

@@ -1,9 +1,78 @@
+/**
+ * Options for configuring `dtStamp()` output format.
+ */
 export interface DtStampOptions {
+    /**
+     * Character(s) between date/time segments.
+     * Ignored when `compact` is `true`.
+     * @default "_"
+     */
     delimiter?: string;
+    /**
+     * Include milliseconds in the time portion.
+     * @default false
+     */
     ms?: boolean;
+    /**
+     * Timezone to use for extracting date/time components.
+     * - `"utc"` -- use UTC methods (`getUTCFullYear`, etc.)
+     * - `"local"` -- use local-time methods (`getFullYear`, etc.)
+     * @default "utc"
+     */
     tz?: "utc" | "local";
+    /**
+     * Which parts of the stamp to include.
+     * - `"datetime"` -- full stamp (date + time)
+     * - `"date"` -- date only (`YYYYMMDD`)
+     * - `"time"` -- time only (`HHmmss` or `HHmmss_SSS` with `ms`)
+     * @default "datetime"
+     */
     parts?: "datetime" | "date" | "time";
+    /**
+     * When `true`, omits the delimiter entirely (equivalent to `delimiter: ""`).
+     * @default false
+     */
     compact?: boolean;
 }
+/**
+ * Format a `Date` into a filesystem/log-safe timestamp string.
+ *
+ * Produces compact, sortable stamps suitable for file names, log prefixes,
+ * and anywhere a human-readable but machine-sortable date/time is needed.
+ *
+ * @param date - Date to format. Defaults to `new Date()` when `null` or omitted.
+ * @param options - Formatting options (delimiter, milliseconds, timezone, parts, compact)
+ * @returns Formatted timestamp string
+ *
+ * @example Default (UTC datetime with underscore delimiter)
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"));
+ * // "20240315_103045"
+ * ```
+ *
+ * @example Compact with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { compact: true, ms: true });
+ * // "20240315103045123"
+ * ```
+ *
+ * @example Date only
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "date" });
+ * // "20240315"
+ * ```
+ *
+ * @example Time only with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "time", ms: true });
+ * // "103045_123"
+ * ```
+ *
+ * @example Custom delimiter
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { delimiter: "-" });
+ * // "20240315-103045"
+ * ```
+ */
 export declare function dtStamp(date?: Date | null, options?: DtStampOptions): string;
 //# sourceMappingURL=format_dt.d.ts.map

package/dist/cjs/src/utils/format_dt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format_dt.d.ts","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CA8C5E"}
+{"version":3,"file":"format_dt.d.ts","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;;OAKG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CA8C5E"}

package/dist/cjs/src/utils/format_dt.js

@@ -1,6 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dtStamp = dtStamp;
+/**
+ * Format a `Date` into a filesystem/log-safe timestamp string.
+ *
+ * Produces compact, sortable stamps suitable for file names, log prefixes,
+ * and anywhere a human-readable but machine-sortable date/time is needed.
+ *
+ * @param date - Date to format. Defaults to `new Date()` when `null` or omitted.
+ * @param options - Formatting options (delimiter, milliseconds, timezone, parts, compact)
+ * @returns Formatted timestamp string
+ *
+ * @example Default (UTC datetime with underscore delimiter)
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"));
+ * // "20240315_103045"
+ * ```
+ *
+ * @example Compact with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { compact: true, ms: true });
+ * // "20240315103045123"
+ * ```
+ *
+ * @example Date only
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "date" });
+ * // "20240315"
+ * ```
+ *
+ * @example Time only with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "time", ms: true });
+ * // "103045_123"
+ * ```
+ *
+ * @example Custom delimiter
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { delimiter: "-" });
+ * // "20240315-103045"
+ * ```
+ */
 function dtStamp(date, options) {
     const d = date ?? new Date();
     const { delimiter = "_", ms = false, tz = "utc", parts = "datetime", compact = false, } = options ?? {};

package/dist/cjs/src/utils/format_dt.js.map

@@ -1 +1 @@
-{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":";;AAQA,0BA8CC;AA9CD,SAAgB,OAAO,CAAC,IAAkB,EAAE,OAAwB;IACnE,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,EACL,SAAS,GAAG,GAAG,EACf,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,KAAK,GAAG,UAAU,EAClB,OAAO,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAElB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrC,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK,CAAC;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;IAE9C,IAAI,EAAE,EAAE,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,CACpB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAClD,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnB,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,QAAQ,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":";;AA6EA,0BA8CC;AAtFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,SAAgB,OAAO,CAAC,IAAkB,EAAE,OAAwB;IACnE,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,EACL,SAAS,GAAG,GAAG,EACf,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,KAAK,GAAG,UAAU,EAClB,OAAO,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAElB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrC,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK,CAAC;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;IAE9C,IAAI,EAAE,EAAE,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,CACpB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAClD,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnB,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,QAAQ,EAAE,CAAC;AACvC,CAAC"}

package/dist/esm/src/utils/format_dt.d.ts

@@ -1,9 +1,78 @@
+/**
+ * Options for configuring `dtStamp()` output format.
+ */
 export interface DtStampOptions {
+    /**
+     * Character(s) between date/time segments.
+     * Ignored when `compact` is `true`.
+     * @default "_"
+     */
     delimiter?: string;
+    /**
+     * Include milliseconds in the time portion.
+     * @default false
+     */
     ms?: boolean;
+    /**
+     * Timezone to use for extracting date/time components.
+     * - `"utc"` -- use UTC methods (`getUTCFullYear`, etc.)
+     * - `"local"` -- use local-time methods (`getFullYear`, etc.)
+     * @default "utc"
+     */
     tz?: "utc" | "local";
+    /**
+     * Which parts of the stamp to include.
+     * - `"datetime"` -- full stamp (date + time)
+     * - `"date"` -- date only (`YYYYMMDD`)
+     * - `"time"` -- time only (`HHmmss` or `HHmmss_SSS` with `ms`)
+     * @default "datetime"
+     */
     parts?: "datetime" | "date" | "time";
+    /**
+     * When `true`, omits the delimiter entirely (equivalent to `delimiter: ""`).
+     * @default false
+     */
     compact?: boolean;
 }
+/**
+ * Format a `Date` into a filesystem/log-safe timestamp string.
+ *
+ * Produces compact, sortable stamps suitable for file names, log prefixes,
+ * and anywhere a human-readable but machine-sortable date/time is needed.
+ *
+ * @param date - Date to format. Defaults to `new Date()` when `null` or omitted.
+ * @param options - Formatting options (delimiter, milliseconds, timezone, parts, compact)
+ * @returns Formatted timestamp string
+ *
+ * @example Default (UTC datetime with underscore delimiter)
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"));
+ * // "20240315_103045"
+ * ```
+ *
+ * @example Compact with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { compact: true, ms: true });
+ * // "20240315103045123"
+ * ```
+ *
+ * @example Date only
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "date" });
+ * // "20240315"
+ * ```
+ *
+ * @example Time only with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "time", ms: true });
+ * // "103045_123"
+ * ```
+ *
+ * @example Custom delimiter
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { delimiter: "-" });
+ * // "20240315-103045"
+ * ```
+ */
 export declare function dtStamp(date?: Date | null, options?: DtStampOptions): string;
 //# sourceMappingURL=format_dt.d.ts.map

package/dist/esm/src/utils/format_dt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format_dt.d.ts","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CA8C5E"}
+{"version":3,"file":"format_dt.d.ts","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;;OAKG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CA8C5E"}

package/dist/esm/src/utils/format_dt.js

@@ -1,3 +1,43 @@
+/**
+ * Format a `Date` into a filesystem/log-safe timestamp string.
+ *
+ * Produces compact, sortable stamps suitable for file names, log prefixes,
+ * and anywhere a human-readable but machine-sortable date/time is needed.
+ *
+ * @param date - Date to format. Defaults to `new Date()` when `null` or omitted.
+ * @param options - Formatting options (delimiter, milliseconds, timezone, parts, compact)
+ * @returns Formatted timestamp string
+ *
+ * @example Default (UTC datetime with underscore delimiter)
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"));
+ * // "20240315_103045"
+ * ```
+ *
+ * @example Compact with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { compact: true, ms: true });
+ * // "20240315103045123"
+ * ```
+ *
+ * @example Date only
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "date" });
+ * // "20240315"
+ * ```
+ *
+ * @example Time only with milliseconds
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "time", ms: true });
+ * // "103045_123"
+ * ```
+ *
+ * @example Custom delimiter
+ * ```typescript
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { delimiter: "-" });
+ * // "20240315-103045"
+ * ```
+ */
 export function dtStamp(date, options) {
     const d = date ?? new Date();
     const { delimiter = "_", ms = false, tz = "utc", parts = "datetime", compact = false, } = options ?? {};

package/dist/esm/src/utils/format_dt.js.map

@@ -1 +1 @@
-{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,OAAO,CAAC,IAAkB,EAAE,OAAwB;IACnE,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,EACL,SAAS,GAAG,GAAG,EACf,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,KAAK,GAAG,UAAU,EAClB,OAAO,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAElB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrC,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK,CAAC;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;IAE9C,IAAI,EAAE,EAAE,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,CACpB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAClD,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnB,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,QAAQ,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,OAAO,CAAC,IAAkB,EAAE,OAAwB;IACnE,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,EACL,SAAS,GAAG,GAAG,EACf,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,KAAK,GAAG,UAAU,EAClB,OAAO,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAElB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrC,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK,CAAC;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;IAE9C,IAAI,EAAE,EAAE,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,CACpB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAClD,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnB,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,QAAQ,EAAE,CAAC;AACvC,CAAC"}