@venizia/ignis-helpers 0.2.0-9 → 0.2.0

package/LICENSE.md

@@ -72,7 +72,6 @@ Ignis uses the following open-source libraries. We are grateful to the authors a
 
 | Library | License | Description |
 |---------|---------|-------------|
-| [Lodash](https://github.com/lodash/lodash) | MIT | Utility library |
 | [reflect-metadata](https://github.com/rbuckton/reflect-metadata) | Apache-2.0 | Metadata reflection API |
 
 ### Documentation Dependencies

package/README.md

@@ -1,32 +1,6 @@
-<div align="center">
+# @venizia/ignis-helpers
 
-<br />
-
-# :fire: IGNIS - `@venizia/ignis-helpers`
-
-**The infrastructure layer: logging, Redis, queues, storage, crypto, networking.**
-
-[![Docs](https://img.shields.io/badge/Docs-ignis.venizia.ai-2563EB.svg?style=flat-square)](https://ignis.venizia.ai/extensions/helpers/)
-[![npm](https://img.shields.io/npm/v/@venizia/ignis-helpers.svg?style=flat-square&color=cb3837&label=@venizia/ignis-helpers)](https://www.npmjs.com/package/@venizia/ignis-helpers)
-[![License: MIT](https://img.shields.io/badge/License-MIT-3DA639.svg?style=flat-square)](LICENSE.md)
-[![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.3-f472b6.svg?style=flat-square&logo=bun&logoColor=white)](https://bun.sh)
-[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-
-[Documentation](https://ignis.venizia.ai/extensions/helpers/) &#8226;
-[Logger](https://ignis.venizia.ai/extensions/helpers/logger/) &#8226;
-[Core API](https://ignis.venizia.ai/references/) &#8226;
-[Changelog](https://ignis.venizia.ai/changelogs/)
-
-</div>
-
----
-
-The pieces every server needs and nobody wants to write again: a scoped logger, Redis, job queues,
-object storage, crypto, cron, sockets, HTTP clients, distributed IDs, worker threads.
-
-Every helper extends `BaseHelper`, so it arrives with a scoped `logger` and an `identifier` already
-wired. `@venizia/ignis` depends on this package - install it directly when you want the helpers
-outside the framework, or when you need one of the sub-paths below.
+Production utilities for IGNIS and for any Bun project: a scoped logger, Redis, queues, object storage, crypto, dates, IDs, networking and worker threads. `@venizia/ignis` already depends on it; install it directly when you use the helpers on their own or need one of the sub-paths below.
 
 ## Install
 
@@ -34,154 +8,102 @@ outside the framework, or when you need one of the sub-paths below.
 bun add @venizia/ignis-helpers
 ```
 
-Nothing heavy comes with it. Every module with a third-party backend declares that backend as an
-**optional peer** - install only the ones you use.
+The root entry loads with no optional peer installed. Every third-party backend (pino, ioredis, bullmq, Kafka, ...) is an optional peer you add only when you use it - see [Entry points](#entry-points).
 
-## Usage
+## Example
+
+Register a logger provider once at the entrypoint, then take scoped loggers and helpers anywhere:
 
 ```typescript
-// src/index.ts - the entrypoint, before anything logs
-import { LoggerFactory } from '@venizia/ignis-helpers';
+// bun add pino ioredis
+import { createRedisHelper, LoggerFactory, RedisModes } from '@venizia/ignis-helpers';
 import { PinoLogger } from '@venizia/ignis-helpers/pino';
 
 LoggerFactory.use({ provider: PinoLogger });
-```
-
-```typescript
-// anywhere else - provider-agnostic
-import { createRedisHelper, ILogger, LoggerFactory, RedisModes } from '@venizia/ignis-helpers';
 
-const logger: ILogger = LoggerFactory.getLogger(['CacheService']);
+const logger = LoggerFactory.getLogger(['CacheService']);
 
 const redis = createRedisHelper({
   mode: RedisModes.SINGLE,
   name: 'cache',
   host: '127.0.0.1',
   port: 6379,
+  password: Bun.env.REDIS_PASSWORD ?? '',
 });
 
 await redis.set({ key: 'user:1', value: { name: 'IGNIS' }, options: { expiresIn: 60_000 } });
-const user = await redis.get<{ name: string }>({ key: 'user:1', transform: JSON.parse });
+const user = await redis.get({ key: 'user:1', transform: JSON.parse });
 
 logger.for('warmup').info('Cache warmed | user: %j', user);
 ```
 
-## Sub-path exports
-
-**This is the one thing to get right.** A helper that value-imports an optional peer is reachable
-**only** from its own sub-path. The root barrel is peer-free by construction: `import
-'@venizia/ignis-helpers'` works with zero peers installed, and your bundler only ever packages the
-backends you imported by name.
-
-| Sub-path | Exports | Peer dependencies to install |
-| :--- | :--- | :--- |
-| `/winston` | `WinstonLogger` | `winston`, `winston-transport`, `winston-daily-rotate-file` |
-| `/pino` | `PinoLogger` | `pino` (+ `pino-pretty` for text format, `pino-roll` for file rotation) |
-| `/bullmq` | `BullMQHelper` | `bullmq` |
-| `/mqtt` | `MQTTClientHelper` | `mqtt` |
-| `/kafka` | `KafkaProducerHelper`, `KafkaConsumerHelper`, `KafkaAdminHelper`, ... | `@platformatic/kafka` |
-| `/minio` | `MinioHelper` | `minio` |
-| `/bun-s3` | `BunS3Helper` | none - Bun's native S3 client |
-| `/socket-io` | `SocketIOServerHelper`, `SocketIOClientHelper` | `socket.io`, `socket.io-client` (+ `@socket.io/redis-adapter`, `@socket.io/redis-emitter` for multi-node) |
-| `/axios` | `AxiosFetcher`, `AxiosNetworkRequest` | `axios` |
-| `/cron` | `CronHelper` | `cron` |
-| `/hashicorp-vault` | `HashiCorpVaultHelper` | `node-vault` |
-| `/dotenv-vault` | `DotenvVaultHelper` | `@dotenvx/dotenvx` |
+Notice that your code only ever types against `ILogger`. `LoggerFactory.use()` swaps the backend for every logger handed out so far. With no provider registered, the factory falls back to winston on the first log call.
 
-```bash
-# example: pino logging + BullMQ jobs + MinIO storage
-bun add pino bullmq minio
+Dates and IDs need no peer at all:
+
+```typescript
+import { TemporalHelper } from '@venizia/ignis-helpers/temporal';
+import { UuidHelper } from '@venizia/ignis-helpers/uuid';
+
+const temporal = new TemporalHelper({ timeZone: 'Asia/Ho_Chi_Minh' });
+const paidAt = temporal.parse({ value: '20260919120000', pattern: 'YYYYMMDDHHmmss' });
+paidAt.toISOString(); // '2026-09-19T05:00:00.000Z'
+
+UuidHelper.getInstance().v7(); // time-ordered, for a database key
 ```
 
-Everything else - Redis (`ioredis` is a real dependency), disk and in-memory storage, crypto,
-network, UID, env, pool, worker threads - comes straight off the root barrel.
-
-## Modules
-
-| Module | What it gives you |
-| :--- | :--- |
-| [logger](https://ignis.venizia.ai/extensions/helpers/logger/) | Scoped `ILogger` over a pluggable winston or pino backend, plus `HfLogger` for hot paths |
-| [redis](https://ignis.venizia.ai/extensions/helpers/redis/) | Single, cluster, and sentinel clients over `ioredis`: key-value, hash, RedisJSON, pub/sub |
-| [queue](https://ignis.venizia.ai/extensions/helpers/queue/) | BullMQ jobs, MQTT topics, [Kafka](https://ignis.venizia.ai/extensions/helpers/kafka/) producers and consumers, plus an in-process `SequentialQueueHelper` |
-| [storage](https://ignis.venizia.ai/extensions/helpers/storage/) | One `IStorageHelper` interface over MinIO/S3, Bun S3, local disk, and memory |
-| [crypto](https://ignis.venizia.ai/extensions/helpers/crypto/) | `AES`, `RSA`, `ECDH` - encryption, signing, and key exchange |
-| [cron](https://ignis.venizia.ai/extensions/helpers/cron/) | `CronHelper`: declarative schedules with lifecycle hooks |
-| [socket](https://ignis.venizia.ai/extensions/helpers/socket-io/) | Socket.IO server and client, plus a [Bun-native WebSocket](https://ignis.venizia.ai/extensions/helpers/websocket/) server |
-| [network](https://ignis.venizia.ai/extensions/helpers/network/) | HTTP fetchers (native or axios) and TCP, TLS, UDP clients and servers |
-| [uid](https://ignis.venizia.ai/extensions/helpers/uid/) | `SnowflakeUidHelper`: 70-bit time-sortable IDs with Base62 encoding, ~4M/sec/worker |
-| [env](https://ignis.venizia.ai/extensions/helpers/env/) | `ApplicationEnvironment`: prefixed, typed access to `process.env` |
-| pool | `BasePoolHelper`: generic resource pooling with an O(1) FIFO wait queue |
-| [secrets](https://ignis.venizia.ai/extensions/helpers/secrets/) | `createSecretsHelper`: system envs, HashiCorp Vault, or dotenvx behind one interface |
-| [worker-thread](https://ignis.venizia.ai/extensions/helpers/worker-thread/) | `WorkerPoolHelper` and a typed message bus for CPU-bound work |
-
-Also on the root barrel: [error](https://ignis.venizia.ai/extensions/helpers/error/) helpers
-(`getError`, `ApplicationError`, `isApplicationError`) and utilities for dates, parsing, promises,
-retries, and requests.
-
-## Logging
-
-Consumers type against **`ILogger`** and never name a concrete logger class. Get one three ways:
-
-| Source | When |
-| :--- | :--- |
-| `this.logger` | Inside anything extending `BaseHelper` - already scoped |
-| `LoggerFactory.getLogger(['Service', 'method'])` | Anywhere; scopes join with `-` |
-| `ApplicationLogger.get('MyService')` | Single-scope shorthand |
-
-`logger.for('methodName')` returns a child logger scoped to that method.
-
-**Exactly five levels**, in severity order: `debug`, `info`, `warn`, `error`, `emerg`. `debug()` is
-gated once at module load by `DEBUG` plus an `NODE_ENV` allowlist.
-
-**Provider selection** happens once, at the entrypoint, through `LoggerFactory.use({ provider })`.
-The factory hands out stable wrappers that resolve their backend lazily, so loggers acquired before
-`use()` re-point to the new provider. With no provider registered, winston loads on the first log
-call.
-
-> [!IMPORTANT]
-> Compiled binaries (`bun build --compile`) **must** call `LoggerFactory.use()` explicitly. The
-> winston fallback is a runtime `require`, which a bundler cannot see - only a class reference
-> carries a provider into a bundle.
-
-`HfLogger` is a separate ring-buffered logger for hot paths where allocation matters, drained by
-`HfLogFlusher`. Reach for it when profiling says to, not before.
-
-### Environment variables
-
-| Variable | Default | Effect |
-| :--- | :--- | :--- |
-| `APP_ENV_LOGGER_LEVEL` | `debug` | Floor below which a line reaches no transport |
-| `APP_ENV_LOGGER_FORMAT` | `text` (winston) / `json` (pino) | `json` or `text`; pino needs `pino-pretty` for `text` |
-| `APP_ENV_LOGGER_FOLDER_PATH` | unset | Set it to enable rotating file output; unset means console or stdout only |
-| `APP_ENV_LOGGER_FILE_FREQUENCY` | `1h` | Rotation interval |
-| `APP_ENV_LOGGER_FILE_MAX_SIZE` | `100m` | Size at which a file rotates |
-| `APP_ENV_LOGGER_FILE_MAX_FILES` | `5d` | Retention |
-| `APP_ENV_LOGGER_FILE_DATE_PATTERN` | `YYYYMMDD_HH` | Filename date pattern (winston only) |
-| `APP_ENV_LOGGER_DGRAM_HOST` / `_PORT` / `_LABEL` / `_LEVELS` | unset | UDP transport for remote log shipping (winston only) |
-| `APP_ENV_LOGGER_DO_REDACT` | `true` | Set `false` to stop redacting secret-looking keys |
-| `APP_ENV_LOGGER_INSPECT_DEPTH` | `5` | Depth before a nested object collapses to `[Object]` |
-| `DEBUG` + `NODE_ENV` | unset | Together gate `debug()`; read once at module load |
-
-Full detail: [Logger reference](https://ignis.venizia.ai/extensions/helpers/logger/).
-
-## Requirements
-
-- **Bun >= 1.3.** Node.js 18+ runs most modules; the Bun-native ones (`/bun-s3`, the WebSocket
-  server) need Bun.
-- `experimentalDecorators` and `emitDecoratorMetadata` must be `true` in your `tsconfig.json`,
-  declared **inline** - Bun does not resolve them through `extends`. Copy them from
-  `@venizia/dev-configs/tsconfig.common.json`.
-- Errors always go through `getError` / `ApplicationError`, never `new Error`. Across package
-  boundaries check with `isApplicationError()`, never `instanceof` - the class has more than one
-  identity in a monorepo.
+`TemporalHelper` uses the runtime's `Temporal` by default. To use a date library you already have, pass `DayjsTemporalAdapter` or `LuxonTemporalAdapter` - this package imports neither.
+
+## Entry points
+
+A helper that imports an optional peer as a value lives only on its own sub-path, so the root entry stays peer-free and a bundler packages only the backends you import.
+
+| Sub-path | What it gives | Extra peers |
+|---|---|---|
+| `.` | Everything peer-free: `LoggerFactory`, `ILogger`, `HfLogger`, Redis helpers (`createRedisHelper`), `SequentialQueueHelper`, disk and in-memory storage, `AES` / `RSA` / `ECDH`, fetch and TCP / TLS / UDP helpers, Bun WebSocket server, `createSecretsHelper`, `ApplicationEnvironment`, `WorkerPoolHelper`, `RetryHelper`, `TemporalHelper`, `UuidHelper`, `SnowflakeUidHelper`, `ModuleUtility`, `getError` | none to load. `ioredis` to use Redis; `hono` for the JSX types |
+| `./core` | Browser-safe runtime classes: `BaseHelper`, the error module, `RetryHelper`, `TemporalHelper`, `UuidHelper`, `TreeBuilder`, `TreeWalker`, `SlugHelper`, `UrlPolicy`, parse utilities | none |
+| `./common` | Constants, types, redaction and resolvers | none |
+| `./uuid` | `UuidHelper` and the standalone `uuidV4`, `uuidV5`, `uuidV7` | none |
+| `./temporal` | `TemporalHelper` and the `Native`, `Dayjs`, `Luxon` temporal adapters | none (your own `dayjs` or `luxon` if you pick that adapter) |
+| `./winston` | `WinstonLogger` | `winston`, `winston-transport`, `winston-daily-rotate-file` |
+| `./pino` | `PinoLogger` | `pino` (`pino-pretty` for text output, `pino-roll` for file rotation) |
+| `./bullmq` | `BullMQHelper` | `bullmq` |
+| `./mqtt` | `MQTTClientHelper` | `mqtt` |
+| `./kafka` | `KafkaProducerHelper`, `KafkaConsumerHelper`, `KafkaAdminHelper`, schema registry, bundler plugins | `@platformatic/kafka` |
+| `./minio` | `MinioHelper` | `minio` |
+| `./bun-s3` | `BunS3Helper` | none - Bun's native S3 client (Bun only) |
+| `./socket-io` | `SocketIOServerHelper`, `SocketIOClientHelper` | `socket.io`, `@socket.io/redis-adapter`, `@socket.io/redis-emitter`; `socket.io-client` for the client |
+| `./axios` | `AxiosFetcher`, `AxiosNetworkRequest` | `axios` |
+| `./cron` | `CronHelper` | `cron` |
+| `./hashicorp-vault` | `HashiCorpVaultHelper` | `node-vault` |
+| `./dotenv-vault` | `DotenvVaultHelper` | `@dotenvx/dotenvx` |
+
+Every entry ships as both CommonJS and ESM.
+
+### Compiled binaries
+
+`ioredis`, `bullmq`, `socket.io-client`, `node-vault` and `@dotenvx/dotenvx` load by name at runtime. A `bun build --compile` binary has no `node_modules` to find them in. Import the peer yourself and hand it over, either through the helper's `module` option or once at the entrypoint:
+
+```typescript
+import * as ioredis from 'ioredis';
+import { ModuleUtility } from '@venizia/ignis-helpers';
+
+ModuleUtility.register({ modules: { ioredis } });
+```
+
+A binary must also call `LoggerFactory.use()` explicitly - the winston fallback cannot reach a bundle. Details: [Module Utility](https://ignis.venizia.ai/references/utilities/module).
+
+## Where it sits
+
+`dev-configs -> inversion -> {filter, helpers} -> {boot, kernel} -> connectors -> {core-worker, core-server} -> atlas`. It depends on `@venizia/ignis-inversion`; `boot`, `kernel` and everything later depend on it.
 
 ## Links
 
-[Helpers documentation](https://ignis.venizia.ai/extensions/helpers/) &#8226;
-[All extensions](https://ignis.venizia.ai/extensions/) &#8226;
-[Best practices](https://ignis.venizia.ai/best-practices/) &#8226;
-[Changelog](https://ignis.venizia.ai/changelogs/) &#8226;
+[Helpers documentation](https://ignis.venizia.ai/extensions/helpers/) -
+[Logger](https://ignis.venizia.ai/extensions/helpers/logger/) -
+[Temporal](https://ignis.venizia.ai/extensions/helpers/temporal/) -
+[UID](https://ignis.venizia.ai/extensions/helpers/uid/) -
+[Changelog](https://ignis.venizia.ai/changelogs/) -
 [Issues](https://github.com/VENIZIA-AI/ignis/issues)
 
-MIT licensed - see [LICENSE.md](LICENSE.md). Questions: developer@venizia.ai
-</content>
+MIT licensed - see [LICENSE.md](LICENSE.md).

package/dist/cjs/common/constants/mime.d.ts

@@ -4,6 +4,73 @@ export declare class MimeTypes {
     static readonly IMAGE = "image";
     static readonly VIDEO = "video";
     static readonly TEXT = "text";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
 }
 export type TMimeTypes = TConstValue<typeof MimeTypes>;
+/** The leading dot is part of the value: `path.extname` returns one. */
+export declare class FileExtensions {
+    static readonly PNG = ".png";
+    static readonly JPG = ".jpg";
+    static readonly JPEG = ".jpeg";
+    static readonly GIF = ".gif";
+    static readonly WEBP = ".webp";
+    static readonly SVG = ".svg";
+    static readonly PDF = ".pdf";
+    static readonly JSON = ".json";
+    static readonly TXT = ".txt";
+    static readonly HTML = ".html";
+    static readonly CSS = ".css";
+    static readonly JS = ".js";
+    static readonly MP4 = ".mp4";
+    static readonly WEBM = ".webm";
+    static readonly MP3 = ".mp3";
+    static readonly WAV = ".wav";
+    static readonly ZIP = ".zip";
+    static readonly CSV = ".csv";
+    static readonly XML = ".xml";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export type TFileExtension = TConstValue<typeof FileExtensions>;
+/** Full content types, as they go on the wire. `MimeTypes` holds only the top-level part. */
+export declare class ContentTypes {
+    static readonly OCTET_STREAM = "application/octet-stream";
+    static readonly PNG = "image/png";
+    static readonly JPEG = "image/jpeg";
+    static readonly GIF = "image/gif";
+    static readonly WEBP = "image/webp";
+    static readonly SVG = "image/svg+xml";
+    static readonly PDF = "application/pdf";
+    static readonly JSON = "application/json";
+    static readonly PLAIN_TEXT = "text/plain";
+    static readonly HTML = "text/html";
+    static readonly CSS = "text/css";
+    static readonly JAVASCRIPT = "text/javascript";
+    static readonly MP4 = "video/mp4";
+    static readonly WEBM = "video/webm";
+    static readonly MPEG_AUDIO = "audio/mpeg";
+    static readonly WAV = "audio/wav";
+    static readonly ZIP = "application/zip";
+    static readonly CSV = "text/csv";
+    static readonly XML = "application/xml";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export type TContentType = TConstValue<typeof ContentTypes>;
+/** The extension table and the lookup that reads it, together - the `DurationMultipliers` shape. */
+export declare class ContentTypeTable {
+    /** `satisfies` makes the table total; the declared `string` key keeps a lookup cast-free. */
+    static readonly BY_EXTENSION: Readonly<Partial<Record<string, TContentType>>>;
+    /**
+     * The content type an object name implies. `node:path` is deliberately not used: this file is
+     * reachable from the browser-pure `./common` subpath, and an extension is the tail after the last
+     * dot either way.
+     */
+    static resolve(opts: {
+        filename: string;
+    }): TContentType;
+}
+/** Published before the table moved onto the class; kept as the one-line delegate it now is. */
+export declare const CONTENT_TYPE_BY_EXTENSION: Readonly<Partial<Record<string, TContentType>>>;
 //# sourceMappingURL=mime.d.ts.map

package/dist/cjs/common/constants/mime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,OAAO,aAAa;IACpC,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,UAAU;CAC/B;AACD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,SAAS,CAAC,CAAC"}
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":"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"}

package/dist/cjs/common/constants/mime.js

@@ -1,11 +1,148 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MimeTypes = void 0;
+exports.CONTENT_TYPE_BY_EXTENSION = exports.ContentTypeTable = exports.ContentTypes = exports.FileExtensions = exports.MimeTypes = void 0;
 class MimeTypes {
     static { this.UNKNOWN = 'unknown'; }
     static { this.IMAGE = 'image'; }
     static { this.VIDEO = 'video'; }
     static { this.TEXT = 'text'; }
+    static { this.SCHEME_SET = new Set([this.UNKNOWN, this.IMAGE, this.VIDEO, this.TEXT]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
 }
 exports.MimeTypes = MimeTypes;
+/** The leading dot is part of the value: `path.extname` returns one. */
+class FileExtensions {
+    static { this.PNG = '.png'; }
+    static { this.JPG = '.jpg'; }
+    static { this.JPEG = '.jpeg'; }
+    static { this.GIF = '.gif'; }
+    static { this.WEBP = '.webp'; }
+    static { this.SVG = '.svg'; }
+    static { this.PDF = '.pdf'; }
+    static { this.JSON = '.json'; }
+    static { this.TXT = '.txt'; }
+    static { this.HTML = '.html'; }
+    static { this.CSS = '.css'; }
+    static { this.JS = '.js'; }
+    static { this.MP4 = '.mp4'; }
+    static { this.WEBM = '.webm'; }
+    static { this.MP3 = '.mp3'; }
+    static { this.WAV = '.wav'; }
+    static { this.ZIP = '.zip'; }
+    static { this.CSV = '.csv'; }
+    static { this.XML = '.xml'; }
+    static { this.SCHEME_SET = new Set([
+        this.PNG,
+        this.JPG,
+        this.JPEG,
+        this.GIF,
+        this.WEBP,
+        this.SVG,
+        this.PDF,
+        this.JSON,
+        this.TXT,
+        this.HTML,
+        this.CSS,
+        this.JS,
+        this.MP4,
+        this.WEBM,
+        this.MP3,
+        this.WAV,
+        this.ZIP,
+        this.CSV,
+        this.XML,
+    ]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.FileExtensions = FileExtensions;
+/** Full content types, as they go on the wire. `MimeTypes` holds only the top-level part. */
+class ContentTypes {
+    static { this.OCTET_STREAM = 'application/octet-stream'; }
+    static { this.PNG = 'image/png'; }
+    static { this.JPEG = 'image/jpeg'; }
+    static { this.GIF = 'image/gif'; }
+    static { this.WEBP = 'image/webp'; }
+    static { this.SVG = 'image/svg+xml'; }
+    static { this.PDF = 'application/pdf'; }
+    static { this.JSON = 'application/json'; }
+    static { this.PLAIN_TEXT = 'text/plain'; }
+    static { this.HTML = 'text/html'; }
+    static { this.CSS = 'text/css'; }
+    static { this.JAVASCRIPT = 'text/javascript'; }
+    static { this.MP4 = 'video/mp4'; }
+    static { this.WEBM = 'video/webm'; }
+    static { this.MPEG_AUDIO = 'audio/mpeg'; }
+    static { this.WAV = 'audio/wav'; }
+    static { this.ZIP = 'application/zip'; }
+    static { this.CSV = 'text/csv'; }
+    static { this.XML = 'application/xml'; }
+    static { this.SCHEME_SET = new Set([
+        this.OCTET_STREAM,
+        this.PNG,
+        this.JPEG,
+        this.GIF,
+        this.WEBP,
+        this.SVG,
+        this.PDF,
+        this.JSON,
+        this.PLAIN_TEXT,
+        this.HTML,
+        this.CSS,
+        this.JAVASCRIPT,
+        this.MP4,
+        this.WEBM,
+        this.MPEG_AUDIO,
+        this.WAV,
+        this.ZIP,
+        this.CSV,
+        this.XML,
+    ]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.ContentTypes = ContentTypes;
+/** The extension table and the lookup that reads it, together - the `DurationMultipliers` shape. */
+class ContentTypeTable {
+    /** `satisfies` makes the table total; the declared `string` key keeps a lookup cast-free. */
+    static { this.BY_EXTENSION = {
+        [FileExtensions.PNG]: ContentTypes.PNG,
+        [FileExtensions.JPG]: ContentTypes.JPEG,
+        [FileExtensions.JPEG]: ContentTypes.JPEG,
+        [FileExtensions.GIF]: ContentTypes.GIF,
+        [FileExtensions.WEBP]: ContentTypes.WEBP,
+        [FileExtensions.SVG]: ContentTypes.SVG,
+        [FileExtensions.PDF]: ContentTypes.PDF,
+        [FileExtensions.JSON]: ContentTypes.JSON,
+        [FileExtensions.TXT]: ContentTypes.PLAIN_TEXT,
+        [FileExtensions.HTML]: ContentTypes.HTML,
+        [FileExtensions.CSS]: ContentTypes.CSS,
+        [FileExtensions.JS]: ContentTypes.JAVASCRIPT,
+        [FileExtensions.MP4]: ContentTypes.MP4,
+        [FileExtensions.WEBM]: ContentTypes.WEBM,
+        [FileExtensions.MP3]: ContentTypes.MPEG_AUDIO,
+        [FileExtensions.WAV]: ContentTypes.WAV,
+        [FileExtensions.ZIP]: ContentTypes.ZIP,
+        [FileExtensions.CSV]: ContentTypes.CSV,
+        [FileExtensions.XML]: ContentTypes.XML,
+    }; }
+    /**
+     * The content type an object name implies. `node:path` is deliberately not used: this file is
+     * reachable from the browser-pure `./common` subpath, and an extension is the tail after the last
+     * dot either way.
+     */
+    static resolve(opts) {
+        const { filename } = opts;
+        const lastDot = filename.lastIndexOf('.');
+        const extension = lastDot === -1 ? '' : filename.slice(lastDot).toLowerCase();
+        return this.BY_EXTENSION[extension] ?? ContentTypes.OCTET_STREAM;
+    }
+}
+exports.ContentTypeTable = ContentTypeTable;
+/** Published before the table moved onto the class; kept as the one-line delegate it now is. */
+exports.CONTENT_TYPE_BY_EXTENSION = ContentTypeTable.BY_EXTENSION;
 //# sourceMappingURL=mime.js.map

package/dist/cjs/common/constants/mime.js.map

@@ -1 +1 @@
-{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":";;;AAEA,MAAa,SAAS;aACJ,YAAO,GAAG,SAAS,CAAC;aACpB,UAAK,GAAG,OAAO,CAAC;aAChB,UAAK,GAAG,OAAO,CAAC;aAChB,SAAI,GAAG,MAAM,CAAC;;AAJhC,8BAKC"}
+{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":";;;AAEA,MAAa,SAAS;aACJ,YAAO,GAAG,SAAS,CAAC;aACpB,UAAK,GAAG,OAAO,CAAC;aAChB,UAAK,GAAG,OAAO,CAAC;aAChB,SAAI,GAAG,MAAM,CAAC;aAEd,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAEhG,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAVH,8BAWC;AAGD,wEAAwE;AACxE,MAAa,cAAc;aACT,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,OAAE,GAAG,KAAK,CAAC;aACX,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aAEb,eAAU,GAAG,IAAI,GAAG,CAAS;QAC3C,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,EAAE;QACP,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;KACT,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AA7CH,wCA8CC;AAGD,6FAA6F;AAC7F,MAAa,YAAY;aACP,iBAAY,GAAG,0BAA0B,CAAC;aAC1C,QAAG,GAAG,WAAW,CAAC;aAClB,SAAI,GAAG,YAAY,CAAC;aACpB,QAAG,GAAG,WAAW,CAAC;aAClB,SAAI,GAAG,YAAY,CAAC;aACpB,QAAG,GAAG,eAAe,CAAC;aACtB,QAAG,GAAG,iBAAiB,CAAC;aACxB,SAAI,GAAG,kBAAkB,CAAC;aAC1B,eAAU,GAAG,YAAY,CAAC;aAC1B,SAAI,GAAG,WAAW,CAAC;aACnB,QAAG,GAAG,UAAU,CAAC;aACjB,eAAU,GAAG,iBAAiB,CAAC;aAC/B,QAAG,GAAG,WAAW,CAAC;aAClB,SAAI,GAAG,YAAY,CAAC;aACpB,eAAU,GAAG,YAAY,CAAC;aAC1B,QAAG,GAAG,WAAW,CAAC;aAClB,QAAG,GAAG,iBAAiB,CAAC;aACxB,QAAG,GAAG,UAAU,CAAC;aACjB,QAAG,GAAG,iBAAiB,CAAC;aAExB,eAAU,GAAG,IAAI,GAAG,CAAS;QAC3C,IAAI,CAAC,YAAY;QACjB,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,UAAU;QACf,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,UAAU;QACf,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,UAAU;QACf,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;KACT,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AA7CH,oCA8CC;AAGD,oGAAoG;AACpG,MAAa,gBAAgB;IAC3B,6FAA6F;aAC7E,iBAAY,GAAoD;QAC9E,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,IAAI;QACvC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,UAAU;QAC7C,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,UAAU;QAC5C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,UAAU;QAC7C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;KACkB,CAAC;IAE3D;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,IAA0B;QACvC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;QAC1B,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QAE9E,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC;IACnE,CAAC;;AAnCH,4CAoCC;AAED,gGAAgG;AACnF,QAAA,yBAAyB,GAAG,gBAAgB,CAAC,YAAY,CAAC"}

package/dist/cjs/common/redact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/common/redact.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,QAAQ,eAAe,CAAC;AA4ErC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,EACd,OAAO,OAAO,CAAC,MAAM,CAAC,EACtB,QAAO,MAAiB,KACvB,OAUF,CAAC;AAEF,4dAA4d;AAC5d,eAAO,MAAM,UAAU,GAAI,MAAM;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OAMrE,CAAC;AAEF,sPAAsP;AACtP,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAmBlD,CAAC"}
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/common/redact.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,QAAQ,eAAe,CAAC;AA4HrC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,EACd,OAAO,OAAO,CAAC,MAAM,CAAC,EACtB,QAAO,MAAiB,KACvB,OAWF,CAAC;AAEF,4dAA4d;AAC5d,eAAO,MAAM,UAAU,GAAI,MAAM;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OASrE,CAAC;AAEF,sPAAsP;AACtP,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAmBlD,CAAC"}

package/dist/cjs/common/redact.js

@@ -24,8 +24,36 @@ const SECRET_KEY_PATTERN = new RegExp([
 exports.REDACTED = '[REDACTED]';
 /** Kill-switch for local debugging: only the literal `false` disables redaction (fail-closed); read per call so it can be flipped at runtime. Never disable in production. */
 const isRedactionEnabled = () => globalThis.process?.env?.APP_ENV_LOGGER_DO_REDACT !== 'false';
+/** Longest string a log line carries whole. `APP_ENV_LOGGER_MAX_STRING_LENGTH=0` turns capping off. */
+const DEFAULT_MAX_STRING_LENGTH = 2048;
+const resolveMaxStringLength = () => {
+    const configured = Number(globalThis.process?.env?.APP_ENV_LOGGER_MAX_STRING_LENGTH);
+    return Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_MAX_STRING_LENGTH;
+};
+/**
+ * Keys whose value is long BY NATURE and useless truncated. A stack trace is the whole reason you
+ * are reading the line.
+ */
+const UNCAPPED_KEYS = new Set(['stack', 'stacktrace', 'stack_trace']);
+/**
+ * Caps a long string, keeping the ORIGINAL LENGTH in the marker - that number is what tells you the
+ * payload was a 300 KB image rather than a truncated sentence.
+ *
+ * A base64 body is the case this exists for: one `data:image/png;base64,...` field turns a request
+ * log into hundreds of kilobytes, and nothing about it is readable.
+ */
+const capString = (opts) => {
+    const { value, key, limit } = opts;
+    if (limit === 0 || value.length <= limit || (key && UNCAPPED_KEYS.has(key.toLowerCase()))) {
+        return value;
+    }
+    return `${value.slice(0, limit)}... [truncated, ${value.length} chars total]`;
+};
 const deepSanitize = (value, context) => {
     const { seen, doRedact, depth } = context;
+    if (typeof value === 'string') {
+        return capString({ value, key: context.key, limit: context.maxStringLength });
+    }
     if (value === null || typeof value !== 'object') {
         return value;
     }
@@ -43,7 +71,12 @@ const deepSanitize = (value, context) => {
         return Array.isArray(value) ? '[Array]' : '[Object]';
     }
     seen.add(value);
-    const nested = { seen, doRedact, depth: depth - 1 };
+    const nested = {
+        seen,
+        doRedact,
+        depth: depth - 1,
+        maxStringLength: context.maxStringLength,
+    };
     // Error keeps name/message/stack NON-enumerable, so Object.keys() skips them and naive redaction would drop the message - reproject into a plain object carrying those fields plus its redacted enumerable own-props.
     if (value instanceof Error) {
         const source = value;
@@ -52,9 +85,12 @@ const deepSanitize = (value, context) => {
             message: value.message,
             stack: value.stack,
         };
-        for (const key of Object.keys(source)) {
+        const sourceKeys = Object.keys(source);
+        for (const key of sourceKeys) {
             result[key] =
-                doRedact && SECRET_KEY_PATTERN.test(key) ? exports.REDACTED : deepSanitize(source[key], nested);
+                doRedact && SECRET_KEY_PATTERN.test(key)
+                    ? exports.REDACTED
+                    : deepSanitize(source[key], { ...nested, key });
         }
         return result;
     }
@@ -63,12 +99,13 @@ const deepSanitize = (value, context) => {
     }
     const source = value;
     const result = {};
-    for (const key of Object.keys(source)) {
+    const sourceKeys = Object.keys(source);
+    for (const key of sourceKeys) {
         if (doRedact && SECRET_KEY_PATTERN.test(key)) {
             result[key] = exports.REDACTED;
             continue;
         }
-        result[key] = deepSanitize(source[key], nested);
+        result[key] = deepSanitize(source[key], { ...nested, key });
     }
     return result;
 };
@@ -89,6 +126,7 @@ const redactSecrets = (value, seen, depth = Infinity) => {
         seen: seen ?? new WeakSet(),
         doRedact: true,
         depth,
+        maxStringLength: resolveMaxStringLength(),
     });
 };
 exports.redactSecrets = redactSecrets;
@@ -98,6 +136,9 @@ const toJsonSafe = (opts) => {
         seen: new WeakSet(),
         doRedact: isRedactionEnabled(),
         depth: opts.depth ?? Infinity,
+        // Capping is STRUCTURAL, like the projection itself: turning redaction off is about key masking,
+        // never about letting a 300 KB base64 field through.
+        maxStringLength: resolveMaxStringLength(),
     });
 };
 exports.toJsonSafe = toJsonSafe;