@arkstack/common 0.19.2 → 0.19.3

package/README.md

@@ -46,11 +46,11 @@ 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:**
@@ -70,13 +70,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.
@@ -88,10 +88,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"
 ```
 
 ---
@@ -101,9 +101,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"
 ```
 
 ---
@@ -124,9 +124,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')
 ```
 
 ---
@@ -140,13 +140,13 @@ 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:
@@ -172,7 +172,7 @@ Logger.configure({
   verbosity: 3, // enables debug output
   quiet: true, // suppresses info and success
   silent: true, // suppresses all output
-});
+})
 ```
 
 ---
@@ -182,10 +182,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
 ```
 
@@ -196,7 +196,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"
 ```
 
@@ -207,8 +207,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
 ```
 
 ---
@@ -224,10 +224,10 @@ Logger.parse(
     ['v1.0.0', 'gray'],
   ],
   ' ',
-); // "Arkstack v1.0.0"
+) // "Arkstack v1.0.0"
 
 // Return instead of print
-const str = Logger.parse([['Ready', 'green']], ' ', false);
+const str = Logger.parse([['Ready', 'green']], ' ', false)
 ```
 
 ---
@@ -237,14 +237,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:3000', 'cyan')
 Logger.log(
   [
     ['PORT', 'bold'],
     ['3000', 'cyan'],
   ],
   ' ',
-);
+)
 ```
 
 ---
@@ -254,8 +254,8 @@ Logger.log(
 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'))
 ```
 
 ---
@@ -265,9 +265,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')
 ```
 
 ---
@@ -283,12 +283,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: {...} }
 }
 ```
@@ -320,7 +320,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: '...' }
 ```
 
@@ -331,8 +331,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
 ```
 
 ---
@@ -348,11 +348,7 @@ 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')
 ```
 
 ---
@@ -360,12 +356,12 @@ ErrorHandler.logUnhandledError(
 #### 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:
@@ -377,7 +373,7 @@ import {
   serializeError,
   logUnhandledError,
   // ...
-} from '@arkstack/common';
+} from '@arkstack/common'
 ```
 
 ---
@@ -393,9 +389,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')
 ```
 
 ---
@@ -405,10 +401,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'] }
 ```
 
 ---
@@ -422,10 +418,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)
 ```
 
@@ -434,7 +430,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)
 ```
 
 ---
@@ -450,12 +446,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'),
-});
+})
 ```
 
 ---
@@ -465,8 +461,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
 ```
 
 ---
@@ -476,8 +472,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
 ```
 
 ---
@@ -487,9 +483,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
 ```
 
 ---
@@ -499,7 +495,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 } }
 ```
 
@@ -522,9 +518,9 @@ A thin wrapper around [`@arkstack/encryption`](https://www.npmjs.com/package/@ar
 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"
 ```
 
@@ -535,7 +531,7 @@ 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"
 ```
 
@@ -556,11 +552,11 @@ A `Cipher` bound to the application key, for encrypting many values without re-d
 #### Key utilities
 
 ```ts
-Encryption.generateKey();                   // random base64url key
-await Encryption.generateKeyPair();         // { publicKey, privateKey } ECDH identity
-await Encryption.deriveKey(password);       // PBKDF2 → { key, salt, iterations }
-await Encryption.compareKeys(left, right);  // constant time
-await Encryption.fingerprint();             // displayable digest of the app key
+Encryption.generateKey() // random base64url key
+await Encryption.generateKeyPair() // { publicKey, privateKey } ECDH identity
+await Encryption.deriveKey(password) // PBKDF2 → { key, salt, iterations }
+await Encryption.compareKeys(left, right) // constant time
+await Encryption.fingerprint() // displayable digest of the app key
 ```
 
 ---
@@ -568,14 +564,14 @@ await Encryption.fingerprint();             // displayable digest of the app key
 #### End-to-end encryption
 
 ```ts
-const channel = await Encryption.channel(myPrivateKey, peerPublicKey);
+const channel = await Encryption.channel(myPrivateKey, peerPublicKey)
 
-await channel.decrypt(await channel.encrypt('hey'));
+await channel.decrypt(await channel.encrypt('hey'))
 
-await Encryption.seal('anonymous tip', peerPublicKey);
-await Encryption.open(payload, myPrivateKey);
+await Encryption.seal('anonymous tip', peerPublicKey)
+await Encryption.open(payload, myPrivateKey)
 
-await Encryption.safetyNumber(myPublicKey, peerPublicKey);
+await Encryption.safetyNumber(myPublicKey, peerPublicKey)
 ```
 
 The full `@arkstack/encryption` surface — `Cipher`, `Codec`, `EncryptionKey`, `KeyPair`, `Keys`, `SealedBox`, `SecureChannel`, `NodeCipher` — is re-exported from this package.
@@ -601,9 +597,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)`
@@ -611,7 +607,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?)`
@@ -619,8 +615,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?)`
@@ -628,8 +624,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
 ```
 
 ---
@@ -645,16 +641,16 @@ 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}`);
+    server.listen(port)
+    Logger.success(`Server:http://localhost:${port}`)
   },
   3000,
   appInstance,
-);
+)
 ```
 
 **Globals set:**
@@ -674,9 +670,9 @@ await bootWithDetectedPort(
 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`.
@@ -692,12 +688,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')
+})
 ```
 
 ---
@@ -711,9 +707,9 @@ 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:**
@@ -735,14 +731,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, '…')
 ```
 
 ---
@@ -789,12 +785,12 @@ Key exported types from the package:
 Extracts a safe pagination limit from a query object. Clamps the result between `1` and `50` or the configured default `maxPerPage`, defaulting to `25` or the configured default `perPage`.
 
 ```ts
-import { perPage } from '@arkstack/common';
+import { perPage } from '@arkstack/common'
 
-const limit = perPage({ limit: 100 }); // 50 (clamped)
-const limit2 = perPage({ limit: 100 }, { maxPerPage: 100 }); // 100
-const limit3 = perPage({}); // 25 (default)
-const limit3 = perPage({}, { perPage: 100 }); // 100
+const limit = perPage({ limit: 100 }) // 50 (clamped)
+const limit2 = perPage({ limit: 100 }, { maxPerPage: 100 }) // 100
+const limit3 = perPage({}) // 25 (default)
+const limit3 = perPage({}, { perPage: 100 }) // 100
 ```
 
 #### `resolvePagination(query, defaults?)`
@@ -802,12 +798,12 @@ const limit3 = perPage({}, { perPage: 100 }); // 100
 Extracts the current page and a safe pagination limit from a query object. Clamps the resulting `perPage` between `1` and `50` or the configured default `maxPerPage`, defaulting to `25` or the configured default `perPage`.
 
 ```ts
-import { resolvePagination } from '@arkstack/common';
+import { resolvePagination } from '@arkstack/common'
 
-const limit = resolvePagination({ limit: 100 }); // {perPage: 50, page: 1} (clamped)
-const limi2 = resolvePagination({ limit: 100 }, { maxPerPage: 100 }); // {perPage: 100, page: 1}
-const limit3 = resolvePagination({}); // {perPage: 50, page: 1} (default)
-const limit4 = resolvePagination({}, { perPage: 100, page: 2 }); // {perPage: 100, page: 2}
+const limit = resolvePagination({ limit: 100 }) // {perPage: 50, page: 1} (clamped)
+const limi2 = resolvePagination({ limit: 100 }, { maxPerPage: 100 }) // {perPage: 100, page: 1}
+const limit3 = resolvePagination({}) // {perPage: 50, page: 1} (default)
+const limit4 = resolvePagination({}, { perPage: 100, page: 2 }) // {perPage: 100, page: 2}
 ```
 
 #### `getModel(modelName)`
@@ -815,17 +811,17 @@ const limit4 = resolvePagination({}, { perPage: 100, page: 2 }); // {perPage: 10
 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
 ```