@arkstack/common 0.7.8 → 0.7.10

package/README.md

@@ -44,22 +44,22 @@ Provides core application-level utilities for environment variable access, confi
 Reads a value from `process.env` with automatic type coercion. Booleans (`true`, `false`, `on`, `off`), numbers, `null`, and empty strings are all handled gracefully.
 
 ```ts
-import { env } from '@arkstack/common'
+import { env } from '@arkstack/common';
 
-const port = env('PORT', 3000)         // number
-const debug = env('DEBUG', false)      // boolean
-const name = env('APP_NAME', 'App')   // string
+const port = env('PORT', 3000); // number
+const debug = env('DEBUG', false); // boolean
+const name = env('APP_NAME', 'App'); // string
 ```
 
 **Type coercion rules:**
 
-| Raw value | Resolved type |
-|-----------|---------------|
-| `"true"` / `"on"` | `true` |
-| `"false"` / `"off"` | `false` |
-| Numeric string | `number` |
-| `"null"` | `null` |
-| `""` | `undefined` (falls back to `defaultValue`) |
+| Raw value           | Resolved type                              |
+| ------------------- | ------------------------------------------ |
+| `"true"` / `"on"`   | `true`                                     |
+| `"false"` / `"off"` | `false`                                    |
+| Numeric string      | `number`                                   |
+| `"null"`            | `null`                                     |
+| `""`                | `undefined` (falls back to `defaultValue`) |
 
 ---
 
@@ -68,13 +68,13 @@ const name = env('APP_NAME', 'App')   // string
 Loads and merges all configuration files from the build output's `config/` directory. Supports dot-path key access with full TypeScript inference.
 
 ```ts
-import { config } from '@arkstack/common'
+import { config } from '@arkstack/common';
 
 // Get the full config object
-const allConfig = config()
+const allConfig = config();
 
 // Access a nested key
-const dbHost = config('database.host', 'localhost')
+const dbHost = config('database.host', 'localhost');
 ```
 
 Config files are loaded from the resolved `outputDir()` using `createRequire`. Middleware config files are skipped when running in CLI context.
@@ -86,10 +86,10 @@ Config files are loaded from the resolved `outputDir()` using `createRequire`. M
 Builds a fully-qualified application URL from `APP_URL` and `PORT` environment variables.
 
 ```ts
-import { appUrl } from '@arkstack/common'
+import { appUrl } from '@arkstack/common';
 
-appUrl()               // "http://localhost:3000"
-appUrl('/api/health')  // "http://localhost:3000/api/health"
+appUrl(); // "http://localhost:3000"
+appUrl('/api/health'); // "http://localhost:3000/api/health"
 ```
 
 ---
@@ -99,9 +99,9 @@ appUrl('/api/health')  // "http://localhost:3000/api/health"
 Returns `'dev'` or `'prod'` based on the `NODE_ENV` environment variable. Defaults to `'dev'` for any unrecognised value.
 
 ```ts
-import { nodeEnv } from '@arkstack/common'
+import { nodeEnv } from '@arkstack/common';
 
-nodeEnv() // "dev" | "prod"
+nodeEnv(); // "dev" | "prod"
 ```
 
 ---
@@ -110,10 +110,10 @@ nodeEnv() // "dev" | "prod"
 
 Resolves the build output directory. In development, defaults to `.arkstack/build`; in production, to `dist`. Both can be overridden via environment variables:
 
-| Variable | Context | Default |
-|----------|---------|---------|
+| Variable         | Context     | Default           |
+| ---------------- | ----------- | ----------------- |
 | `OUTPUT_DIR_DEV` | Development | `.arkstack/build` |
-| `OUTPUT_DIR` | Production | `dist` |
+| `OUTPUT_DIR`     | Production  | `dist`            |
 
 ---
 
@@ -122,9 +122,9 @@ Resolves the build output directory. In development, defaults to `.arkstack/buil
 Dynamically imports a file using [Jiti](https://github.com/unjs/jiti), with TypeScript and `tsconfig` path support. Useful for loading user-defined config or plugin files at runtime.
 
 ```ts
-import { importFile } from '@arkstack/common'
+import { importFile } from '@arkstack/common';
 
-const module = await importFile<{ default: MyConfig }>('./config/app.ts')
+const module = await importFile<{ default: MyConfig }>('./config/app.ts');
 ```
 
 ---
@@ -138,24 +138,24 @@ A structured, chalk-powered console logger with verbosity control, two-column fo
 #### Basic log levels
 
 ```ts
-import { Logger } from '@arkstack/common'
+import { Logger } from '@arkstack/common';
 
-Logger.success('Server started')
-Logger.info('Listening on port 3000')
-Logger.warn('Deprecated option used')
-Logger.error('Something went wrong', false)   // false = don't exit
-Logger.debug('Internal state dump')           // only shown at verbosity >= 3
+Logger.success('Server started');
+Logger.info('Listening on port 3000');
+Logger.warn('Deprecated option used');
+Logger.error('Something went wrong', false); // false = don't exit
+Logger.debug('Internal state dump'); // only shown at verbosity >= 3
 ```
 
 Each level uses a distinct icon and colour:
 
-| Method | Icon | Colour |
-|--------|------|--------|
-| `success` | `✓` | Green |
-| `info` | `ℹ` | Blue |
-| `warn` | `⚠` | Yellow |
-| `error` | `✖` | Red |
-| `debug` | `🐛` | Gray |
+| Method    | Icon | Colour |
+| --------- | ---- | ------ |
+| `success` | `✓`  | Green  |
+| `info`    | `ℹ`  | Blue   |
+| `warn`    | `⚠`  | Yellow |
+| `error`   | `✖`  | Red    |
+| `debug`   | `🐛` | Gray   |
 
 The second argument for all level methods is `exit` (boolean). When `true`, the process exits after logging. `error` exits by default (`exit = true`); all others default to `false`.
 
@@ -167,10 +167,10 @@ Sets global verbosity and suppression behaviour.
 
 ```ts
 Logger.configure({
-  verbosity: 3,    // enables debug output
-  quiet: true,     // suppresses info and success
-  silent: true,    // suppresses all output
-})
+  verbosity: 3, // enables debug output
+  quiet: true, // suppresses info and success
+  silent: true, // suppresses all output
+});
 ```
 
 ---
@@ -180,10 +180,10 @@ Logger.configure({
 Renders a right-aligned two-column layout padded to the terminal width.
 
 ```ts
-Logger.twoColumnDetail('Route', 'GET /api/users')
+Logger.twoColumnDetail('Route', 'GET /api/users');
 // "Route ......................................... GET /api/users"
 
-const row = Logger.twoColumnDetail('Route', 'GET /api/users', false)
+const row = Logger.twoColumnDetail('Route', 'GET /api/users', false);
 // returns [name, dots, value] without printing
 ```
 
@@ -194,7 +194,7 @@ const row = Logger.twoColumnDetail('Route', 'GET /api/users', false)
 Similar to `twoColumnDetail`, but uses a fixed width with space padding rather than dots. Useful for command help listings.
 
 ```ts
-Logger.describe('--port', 'Port to listen on', 40)
+Logger.describe('--port', 'Port to listen on', 40);
 // "--port                    Port to listen on"
 ```
 
@@ -205,8 +205,8 @@ Logger.describe('--port', 'Port to listen on', 40)
 Like `twoColumnDetail`, but wraps the left column with a coloured background badge based on `status`.
 
 ```ts
-Logger.split('Database', 'Connected', 'success')
-Logger.split('Migration', 'Failed', 'error', true) // exits after logging
+Logger.split('Database', 'Connected', 'success');
+Logger.split('Migration', 'Failed', 'error', true); // exits after logging
 ```
 
 ---
@@ -216,13 +216,16 @@ Logger.split('Migration', 'Failed', 'error', true) // exits after logging
 Composes a styled string from a `[text, chalkStyle]` pair array.
 
 ```ts
-Logger.parse([
-  ['Arkstack', 'bold'],
-  ['v1.0.0', 'gray'],
-], ' ') // "Arkstack v1.0.0"
+Logger.parse(
+  [
+    ['Arkstack', 'bold'],
+    ['v1.0.0', 'gray'],
+  ],
+  ' ',
+); // "Arkstack v1.0.0"
 
 // Return instead of print
-const str = Logger.parse([['Ready', 'green']], ' ', false)
+const str = Logger.parse([['Ready', 'green']], ' ', false);
 ```
 
 ---
@@ -232,8 +235,14 @@ const str = Logger.parse([['Ready', 'green']], ' ', false)
 A flexible polymorphic logger that accepts either a string + style, or a `LoggerParseSignature` array. Returns the `Logger` class when called with no arguments.
 
 ```ts
-Logger.log('PORT:3000', 'cyan')
-Logger.log([['PORT', 'bold'], ['3000', 'cyan']], ' ')
+Logger.log('PORT:3000', 'cyan');
+Logger.log(
+  [
+    ['PORT', 'bold'],
+    ['3000', 'cyan'],
+  ],
+  ' ',
+);
 ```
 
 ---
@@ -243,8 +252,8 @@ Logger.log([['PORT', 'bold'], ['3000', 'cyan']], ' ')
 Returns a function that applies a chain of chalk styles to any input.
 
 ```ts
-const highlight = Logger.chalker(['bold', 'green'])
-console.log(highlight('Ready'))
+const highlight = Logger.chalker(['bold', 'green']);
+console.log(highlight('Ready'));
 ```
 
 ---
@@ -254,9 +263,9 @@ console.log(highlight('Ready'))
 Returns a `Console`-compatible object with `log`, `debug`, `warn`, `info`, and `error` methods. Can be used as a drop-in replacement for `globalThis.console`.
 
 ```ts
-const console = Logger.console()
-console.log('hello')
-console.warn('watch out')
+const console = Logger.console();
+console.log('hello');
+console.warn('watch out');
 ```
 
 ---
@@ -272,12 +281,12 @@ A static utility class for normalising, serialising, classifying, and logging er
 The primary method. Converts any thrown value into a consistent `ArkstackErrorPayload` object, handling validation errors, model-not-found errors, and generic errors uniformly.
 
 ```ts
-import { ErrorHandler } from '@arkstack/common'
+import { ErrorHandler } from '@arkstack/common';
 
 try {
   // ...
 } catch (err) {
-  const payload = ErrorHandler.createErrorPayload(err, 'Request failed')
+  const payload = ErrorHandler.createErrorPayload(err, 'Request failed');
   // { status: 'error', code: 422, message: '...', errors: {...} }
 }
 ```
@@ -296,11 +305,11 @@ try {
 
 **Classification logic:**
 
-| Error type | `code` | `errors` populated |
-|------------|--------|--------------------|
-| Validation error (has `.errors`) | `statusCode` / `status` or `422` | Yes |
-| Model not found (has `.getModelName()`) | `404` | No |
-| Generic error | `statusCode` / `status` or `500` | Stack trace as object |
+| Error type                              | `code`                           | `errors` populated    |
+| --------------------------------------- | -------------------------------- | --------------------- |
+| Validation error (has `.errors`)        | `statusCode` / `status` or `422` | Yes                   |
+| Model not found (has `.getModelName()`) | `404`                            | No                    |
+| Generic error                           | `statusCode` / `status` or `500` | Stack trace as object |
 
 ---
 
@@ -309,7 +318,7 @@ try {
 Recursively serialises any value — including `Error` instances and circular references — into a plain JSON-safe object. Circular references are replaced with `'[Circular]'`.
 
 ```ts
-const serialized = ErrorHandler.serializeError(new Error('oops'))
+const serialized = ErrorHandler.serializeError(new Error('oops'));
 // { name: 'Error', message: 'oops', stack: '...' }
 ```
 
@@ -320,8 +329,8 @@ const serialized = ErrorHandler.serializeError(new Error('oops'))
 Ensures a status code is a valid integer in the range `100–599`. Returns the fallback (default `500`) for anything invalid.
 
 ```ts
-ErrorHandler.normalizeStatusCode('422')  // 422
-ErrorHandler.normalizeStatusCode('xyz')  // 500
+ErrorHandler.normalizeStatusCode('422'); // 422
+ErrorHandler.normalizeStatusCode('xyz'); // 500
 ```
 
 ---
@@ -337,7 +346,11 @@ Returns a Pino logger instance that writes to `storage/logs/error.log` (created
 Persists an unhandled error to the error log file, including the serialised error and the associated request context.
 
 ```ts
-ErrorHandler.logUnhandledError(err, { method: 'GET', url: '/api' }, 'Unhandled exception')
+ErrorHandler.logUnhandledError(
+  err,
+  { method: 'GET', url: '/api' },
+  'Unhandled exception',
+);
 ```
 
 ---
@@ -345,12 +358,12 @@ ErrorHandler.logUnhandledError(err, { method: 'GET', url: '/api' }, 'Unhandled e
 #### Classification helpers
 
 ```ts
-ErrorHandler.isValidationError(err)      // true if err.errors is defined
-ErrorHandler.isModelNotFoundError(err)   // true if err.getModelName is a function
-ErrorHandler.shouldLogError(err)         // false for validation/model-not-found errors
-ErrorHandler.shouldHideStack()           // true if HIDE_ERROR_STACK env is set
-ErrorHandler.getPrimaryError(err)        // unwraps err.cause if present
-ErrorHandler.toErrorShape(value)         // casts unknown to ArkstackErrorShape if object
+ErrorHandler.isValidationError(err); // true if err.errors is defined
+ErrorHandler.isModelNotFoundError(err); // true if err.getModelName is a function
+ErrorHandler.shouldLogError(err); // false for validation/model-not-found errors
+ErrorHandler.shouldHideStack(); // true if HIDE_ERROR_STACK env is set
+ErrorHandler.getPrimaryError(err); // unwraps err.cause if present
+ErrorHandler.toErrorShape(value); // casts unknown to ArkstackErrorShape if object
 ```
 
 All static methods are also exported as named standalone functions for convenience:
@@ -362,7 +375,7 @@ import {
   serializeError,
   logUnhandledError,
   // ...
-} from '@arkstack/common'
+} from '@arkstack/common';
 ```
 
 ---
@@ -378,9 +391,9 @@ A three-level exception hierarchy for structured error throwing.
 Base class extending `Error`. Sets `.name` to `'Exception'`.
 
 ```ts
-import { Exception } from '@arkstack/common'
+import { Exception } from '@arkstack/common';
 
-throw new Exception('Something went wrong')
+throw new Exception('Something went wrong');
 ```
 
 ---
@@ -390,10 +403,10 @@ throw new Exception('Something went wrong')
 Extends `Exception`. Adds `statusCode` (default `400`) and an optional `errors` map for field-level validation errors.
 
 ```ts
-import { AppException } from '@arkstack/common'
+import { AppException } from '@arkstack/common';
 
-const err = new AppException('Validation failed', 422)
-err.errors = { email: ['Email is required'] }
+const err = new AppException('Validation failed', 422);
+err.errors = { email: ['Email is required'] };
 ```
 
 ---
@@ -407,10 +420,10 @@ Extends `AppException`. Intended for HTTP request-level errors. Provides two sta
 Throws a `RequestException` if the value is `null` or `undefined`. Narrows the type on success.
 
 ```ts
-import { RequestException } from '@arkstack/common'
+import { RequestException } from '@arkstack/common';
 
-const user = await User.find(id)
-RequestException.assertNotEmpty(user, 'User not found', 404)
+const user = await User.find(id);
+RequestException.assertNotEmpty(user, 'User not found', 404);
 // user is now User (not null | undefined)
 ```
 
@@ -419,7 +432,7 @@ RequestException.assertNotEmpty(user, 'User not found', 404)
 Throws if the condition is truthy.
 
 ```ts
-RequestException.abortIf(!user.isActive, 'Account is suspended', 403)
+RequestException.abortIf(!user.isActive, 'Account is suspended', 403);
 ```
 
 ---
@@ -435,12 +448,12 @@ A global, named hook registry for extending Arkstack internals without modifying
 Registers a hook. Multiple calls for the same name are merged.
 
 ```ts
-import { Hook } from '@arkstack/common'
+import { Hook } from '@arkstack/common';
 
 Hook.set('request:handle', {
   before: (ctx) => console.log('before handler'),
   after: (ctx) => console.log('after handler'),
-})
+});
 ```
 
 ---
@@ -450,8 +463,8 @@ Hook.set('request:handle', {
 Retrieves the full hook object or a specific positional handler.
 
 ```ts
-const hook = Hook.get('request:handle')           // IHook | undefined
-const before = Hook.get('request:handle', 'before') // function | undefined
+const hook = Hook.get('request:handle'); // IHook | undefined
+const before = Hook.get('request:handle', 'before'); // function | undefined
 ```
 
 ---
@@ -461,8 +474,8 @@ const before = Hook.get('request:handle', 'before') // function | undefined
 Checks whether a hook (or a specific position within it) exists.
 
 ```ts
-Hook.has('request:handle')           // true | false
-Hook.has('request:handle', 'after')  // true | false
+Hook.has('request:handle'); // true | false
+Hook.has('request:handle', 'after'); // true | false
 ```
 
 ---
@@ -472,9 +485,9 @@ Hook.has('request:handle', 'after')  // true | false
 Removes a hook or a single positional handler. If the hook becomes empty after removal, it is deleted entirely. Called with no arguments, it delegates to `Hook.clear()`.
 
 ```ts
-Hook.unset('request:handle', 'before')  // removes only the 'before' handler
-Hook.unset('request:handle')            // removes the entire hook
-Hook.unset()                            // clears all hooks
+Hook.unset('request:handle', 'before'); // removes only the 'before' handler
+Hook.unset('request:handle'); // removes the entire hook
+Hook.unset(); // clears all hooks
 ```
 
 ---
@@ -484,7 +497,7 @@ Hook.unset()                            // clears all hooks
 Returns all registered hooks as a plain record.
 
 ```ts
-const hooks = Hook.getAll()
+const hooks = Hook.getAll();
 // { 'request:handle': { before: fn, after: fn } }
 ```
 
@@ -507,9 +520,9 @@ AES-256-GCM symmetric encryption for sensitive values (e.g. two-factor authentic
 Encrypts a string. Returns a colon-delimited base64url string: `<iv>:<authTag>:<ciphertext>`.
 
 ```ts
-import { Encryption } from '@arkstack/common'
+import { Encryption } from '@arkstack/common';
 
-const token = Encryption.encrypt('my-secret-value')
+const token = Encryption.encrypt('my-secret-value');
 // "abc123:def456:ghi789"
 ```
 
@@ -518,15 +531,15 @@ const token = Encryption.encrypt('my-secret-value')
 Decrypts a payload produced by `encrypt`. Throws if the format is invalid or the key is wrong.
 
 ```ts
-const original = Encryption.decrypt(token)
+const original = Encryption.decrypt(token);
 // "my-secret-value"
 ```
 
 **Environment variable:**
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `TWO_FACTOR_ENCRYPTION_KEY` | Yes | Raw secret; hashed to a 256-bit key internally via SHA-256 |
+| Variable                    | Required | Description                                                |
+| --------------------------- | -------- | ---------------------------------------------------------- |
+| `TWO_FACTOR_ENCRYPTION_KEY` | Yes      | Raw secret; hashed to a 256-bit key internally via SHA-256 |
 
 ---
 
@@ -541,9 +554,9 @@ Password hashing and OTP generation utilities.
 Hashes a string using bcrypt with a salt factor of 10.
 
 ```ts
-import { Hash } from '@arkstack/common'
+import { Hash } from '@arkstack/common';
 
-const hashed = await Hash.make('user-password')
+const hashed = await Hash.make('user-password');
 ```
 
 #### `Hash.verify(value, hashedValue)`
@@ -551,7 +564,7 @@ const hashed = await Hash.make('user-password')
 Compares a plain-text value against a bcrypt hash.
 
 ```ts
-const isValid = await Hash.verify('user-password', hashed)
+const isValid = await Hash.verify('user-password', hashed);
 ```
 
 #### `Hash.otp(digits?, label?, period?)`
@@ -559,8 +572,8 @@ const isValid = await Hash.verify('user-password', hashed)
 Creates a TOTP instance using the `otpauth` library with `SHA1` and a static secret. Suitable for simple time-based OTP flows.
 
 ```ts
-const totp = Hash.otp(6, 'user@example.com', 60)
-const token = totp.generate()
+const totp = Hash.otp(6, 'user@example.com', 60);
+const token = totp.generate();
 ```
 
 #### `Hash.totp(secret, label, issuer?, period?)`
@@ -568,8 +581,8 @@ const token = totp.generate()
 Creates a TOTP instance from a base32-encoded secret. Intended for user-specific TOTP (e.g. authenticator app integration).
 
 ```ts
-const totp = Hash.totp(user.totpSecret, user.email)
-const isValid = totp.validate({ token: userInput }) !== null
+const totp = Hash.totp(user.totpSecret, user.email);
+const isValid = totp.validate({ token: userInput }) !== null;
 ```
 
 ---
@@ -585,23 +598,27 @@ Utilities for starting an HTTP server with automatic port detection and renderin
 Detects whether the preferred port is available (using `detect-port`) and boots the server on the first free port. Also initialises key globals: `env`, `config`, `str`, `app`, and `arkctx`.
 
 ```ts
-import { bootWithDetectedPort } from '@arkstack/common'
+import { bootWithDetectedPort } from '@arkstack/common';
 
-await bootWithDetectedPort(async (port) => {
-  server.listen(port)
-  Logger.success(`Server:http://localhost:${port}`)
-}, 3000, appInstance)
+await bootWithDetectedPort(
+  async (port) => {
+    server.listen(port);
+    Logger.success(`Server:http://localhost:${port}`);
+  },
+  3000,
+  appInstance,
+);
 ```
 
 **Globals set:**
 
-| Global | Value |
-|--------|-------|
-| `globalThis.app` | `() => app` |
-| `globalThis.env` | `env` |
-| `globalThis.config` | `config` |
-| `globalThis.str` | `str` (from `@h3ravel/support`) |
-| `globalThis.arkctx` | `{ runtime: 'HTTP' }` |
+| Global              | Value                           |
+| ------------------- | ------------------------------- |
+| `globalThis.app`    | `() => app`                     |
+| `globalThis.env`    | `env`                           |
+| `globalThis.config` | `config`                        |
+| `globalThis.str`    | `str` (from `@h3ravel/support`) |
+| `globalThis.arkctx` | `{ runtime: 'HTTP' }`           |
 
 ---
 
@@ -610,9 +627,9 @@ await bootWithDetectedPort(async (port) => {
 Renders an error page using the `~arkstack/common.error` view template. Falls back to a human-readable title from a built-in status code map.
 
 ```ts
-import { renderError } from '@arkstack/common'
+import { renderError } from '@arkstack/common';
 
-const html = renderError({ code: 404, message: 'Page not found' })
+const html = renderError({ code: 404, message: 'Page not found' });
 ```
 
 **Built-in status titles:** `400`, `401`, `403`, `404`, `500`, `502`, `503`, `504`.
@@ -628,12 +645,12 @@ const html = renderError({ code: 404, message: 'Page not found' })
 Registers a cleanup callback for `SIGINT`, `SIGTERM`, and `SIGQUIT` signals, ensuring the application shuts down cleanly.
 
 ```ts
-import { bindGracefulShutdown } from '@arkstack/common'
+import { bindGracefulShutdown } from '@arkstack/common';
 
 bindGracefulShutdown(async () => {
-  await db.disconnect()
-  Logger.info('Server shut down gracefully')
-})
+  await db.disconnect();
+  Logger.info('Server shut down gracefully');
+});
 ```
 
 ---
@@ -647,19 +664,19 @@ bindGracefulShutdown(async () => {
 Extends `String.prototype` with four utility methods. Call this once during application bootstrap.
 
 ```ts
-import { loadPrototypes } from '@arkstack/common'
+import { loadPrototypes } from '@arkstack/common';
 
-loadPrototypes()
+loadPrototypes();
 ```
 
 **Methods added:**
 
-| Method | Description | Example |
-|--------|-------------|---------|
-| `.titleCase()` | Converts to Title Case (handles `_` and `-`) | `"hello_world".titleCase()` → `"Hello World"` |
-| `.camelCase()` | Converts to camelCase | `"Hello World".camelCase()` → `"helloWorld"` |
-| `.pascalCase()` | Converts to PascalCase | `"hello world".pascalCase()` → `"HelloWorld"` |
-| `.truncate(len, suffix?)` | Truncates at word boundary | `"Hello World".truncate(7)` → `"Hello..."` |
+| Method                    | Description                                  | Example                                       |
+| ------------------------- | -------------------------------------------- | --------------------------------------------- |
+| `.titleCase()`            | Converts to Title Case (handles `_` and `-`) | `"hello_world".titleCase()` → `"Hello World"` |
+| `.camelCase()`            | Converts to camelCase                        | `"Hello World".camelCase()` → `"helloWorld"`  |
+| `.pascalCase()`           | Converts to PascalCase                       | `"hello world".pascalCase()` → `"HelloWorld"` |
+| `.truncate(len, suffix?)` | Truncates at word boundary                   | `"Hello World".truncate(7)` → `"Hello..."`    |
 
 ---
 
@@ -671,14 +688,14 @@ When `loadPrototypes()` is called and `bootWithDetectedPort()` initialises the r
 
 ```ts
 // Globals (set by bootWithDetectedPort)
-globalThis.env    // GlobalEnv — typed env() accessor
-globalThis.config // GlobalConfig — typed config() accessor
+globalThis.env; // GlobalEnv — typed env() accessor
+globalThis.config; // GlobalConfig — typed config() accessor
 
 // String prototype extensions (set by loadPrototypes)
-"my_string".titleCase()
-"my_string".camelCase()
-"my_string".pascalCase()
-"my long string".truncate(10, '…')
+'my_string'.titleCase();
+'my_string'.camelCase();
+'my_string'.pascalCase();
+'my long string'.truncate(10, '…');
 ```
 
 ---
@@ -689,30 +706,30 @@ globalThis.config // GlobalConfig — typed config() accessor
 
 Key exported types from the package:
 
-| Type | Description |
-|------|-------------|
-| `GlobalEnv` | Typed signature for the `env()` function |
-| `GlobalConfig` | Typed signature for the `config()` function with dot-path support |
-| `ArkstackErrorShape` | Union of common error properties across frameworks (`statusCode`, `status`, `errors`, `cause`, etc.) |
-| `ArkstackErrorPayload` | Normalised HTTP error response shape produced by `ErrorHandler` |
-| `LoggerChalk` | Chalk style identifier(s) accepted by `Logger` methods |
-| `LoggerParseSignature` | Array of `[string, LoggerChalk]` pairs for `Logger.parse()` |
-| `LoggerLog` | Overloaded function type for `Logger.log()` |
+| Type                   | Description                                                                                          |
+| ---------------------- | ---------------------------------------------------------------------------------------------------- |
+| `GlobalEnv`            | Typed signature for the `env()` function                                                             |
+| `GlobalConfig`         | Typed signature for the `config()` function with dot-path support                                    |
+| `ArkstackErrorShape`   | Union of common error properties across frameworks (`statusCode`, `status`, `errors`, `cause`, etc.) |
+| `ArkstackErrorPayload` | Normalised HTTP error response shape produced by `ErrorHandler`                                      |
+| `LoggerChalk`          | Chalk style identifier(s) accepted by `Logger` methods                                               |
+| `LoggerParseSignature` | Array of `[string, LoggerChalk]` pairs for `Logger.parse()`                                          |
+| `LoggerLog`            | Overloaded function type for `Logger.log()`                                                          |
 
 ---
 
 ## Environment Variables Reference
 
-| Variable | Module | Required | Description |
-|----------|--------|----------|-------------|
-| `PORT` | `system`, `network` | No | HTTP server port (default: `3000`) |
-| `APP_URL` | `system` | No | Base application URL |
-| `APP_NAME` | `hash` | No | Application name used as TOTP issuer |
-| `NODE_ENV` | `system` | No | `development` or `production` |
-| `OUTPUT_DIR` | `system` | No | Production build output directory (default: `dist`) |
-| `OUTPUT_DIR_DEV` | `system` | No | Development build output directory (default: `.arkstack/build`) |
-| `TWO_FACTOR_ENCRYPTION_KEY` | `encryption` | Yes* | Secret key for AES-256-GCM encryption (*required only if using `Encryption`) |
-| `HIDE_ERROR_STACK` | `ErrorHandler` | No | Set to `true`, `1`, or `on` to suppress stack traces in error payloads |
+| Variable                    | Module              | Required | Description                                                                   |
+| --------------------------- | ------------------- | -------- | ----------------------------------------------------------------------------- |
+| `PORT`                      | `system`, `network` | No       | HTTP server port (default: `3000`)                                            |
+| `APP_URL`                   | `system`            | No       | Base application URL                                                          |
+| `APP_NAME`                  | `hash`              | No       | Application name used as TOTP issuer                                          |
+| `NODE_ENV`                  | `system`            | No       | `development` or `production`                                                 |
+| `OUTPUT_DIR`                | `system`            | No       | Production build output directory (default: `dist`)                           |
+| `OUTPUT_DIR_DEV`            | `system`            | No       | Development build output directory (default: `.arkstack/build`)               |
+| `TWO_FACTOR_ENCRYPTION_KEY` | `encryption`        | Yes\*    | Secret key for AES-256-GCM encryption (\*required only if using `Encryption`) |
+| `HIDE_ERROR_STACK`          | `ErrorHandler`      | No       | Set to `true`, `1`, or `on` to suppress stack traces in error payloads        |
 
 ---
 
@@ -725,28 +742,28 @@ Key exported types from the package:
 Extracts a safe pagination limit from a query object. Clamps the result between `1` and `50`, defaulting to `15`.
 
 ```ts
-import { perPage } from '@arkstack/common'
+import { perPage } from '@arkstack/common';
 
-const limit = perPage({ limit: 100 })  // 50 (clamped)
-const limit2 = perPage({})             // 15 (default)
+const limit = perPage({ limit: 100 }); // 50 (clamped)
+const limit2 = perPage({}); // 15 (default)
 ```
 
 #### `getModel(modelName)`
 
-Dynamically imports an application model by name from the configured models directory (default: `./src/models`). Supports augmenting `ModelRegistry` for type-safe lookups.
+Dynamically imports an application model by name from the configured models directory (default: `./src/app/models`). Supports augmenting `ModelRegistry` for type-safe lookups.
 
 ```ts
-import { getModel } from '@arkstack/common'
+import { getModel } from '@arkstack/common';
 
-const User = await getModel('User')
-const users = await User.findAll()
+const User = await getModel('User');
+const users = await User.findAll();
 
 // With type augmentation:
 declare module '@arkstack/common' {
   interface ModelRegistry {
-    User: typeof User
+    User: typeof User;
   }
 }
 
-const TypedUser = await getModel('User') // typeof User
+const TypedUser = await getModel('User'); // typeof User
 ```