@wireio/shared 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,424 @@
+# @wireio/shared
+
+Core shared utilities for Wire applications, providing a logging framework, type guards, and async helpers that work across browser and Node.js environments.
+
+## Installation
+
+```bash
+pnpm add @wireio/shared
+```
+
+## Modules
+
+- [Logging](#logging) - Flexible logging framework with multiple appenders
+- [Guards](#guards) - Type guards and assertion utilities
+- [Helpers](#helpers) - Async utilities including `Deferred`
+
+---
+
+## Logging
+
+A flexible, extensible logging framework supporting multiple log levels, appenders, and contextual logging.
+
+### Basic Usage
+
+```typescript
+import { getLoggingManager } from "@wireio/shared"
+
+const logManager = getLoggingManager()
+const log = logManager.getLogger("my-module")
+
+log.trace("Detailed trace message")
+log.debug("Debug information")
+log.info("Informational message")
+log.warn("Warning message")
+log.error("Error occurred", new Error("Something went wrong"))
+log.fatal("Fatal error - application cannot continue")
+```
+
+### Log Levels
+
+Levels are ordered by severity (lowest to highest):
+
+| Level | Threshold | Description |
+|-------|-----------|-------------|
+| `trace` | 0 | Fine-grained debugging |
+| `debug` | 1 | Debugging information |
+| `info` | 2 | Informational messages |
+| `warn` | 3 | Warning conditions |
+| `error` | 4 | Error conditions |
+| `fatal` | 5 | Critical failures |
+
+### Configuring the Logging Manager
+
+```typescript
+import { getLoggingManager, Level, ConsoleAppender } from "@wireio/shared"
+
+const logManager = getLoggingManager()
+
+// Set the root logging level
+logManager.setRootLevel(Level.debug)
+
+// Replace default appenders
+logManager.setAppenders(new ConsoleAppender({ prettyPrint: true }))
+
+// Add additional appenders
+logManager.addAppenders(new MyCustomAppender())
+
+// Configure threshold overrides for specific categories
+logManager.addThresholdOverrides(
+  [/^database/, "debug"],  // Enable debug for database.* categories
+  ["auth", "trace"]        // Enable trace for exact "auth" category
+)
+```
+
+### Environment-Based Debug Patterns
+
+Set the `DEBUG_PATTERNS` environment variable to enable debug logging for specific categories:
+
+```bash
+DEBUG_PATTERNS="database.*,auth.*" node app.js
+```
+
+### Level Checking
+
+Check if a level is enabled before expensive operations:
+
+```typescript
+if (log.isDebugEnabled()) {
+  log.debug("Expensive data:", computeExpensiveDebugInfo())
+}
+```
+
+### Log Records
+
+Each log record contains:
+
+```typescript
+interface LogRecord {
+  timestamp: number      // EPOCH Milliseconds
+  category: string       // Logger category
+  level: LevelKind       // Log level
+  message: string        // Log message
+  args?: any[]           // Additional arguments
+  data?: any             // Structured data
+  tags?: string[]        // Tags for filtering
+  url?: string           // Source URL (auto-populated)
+  env?: string           // Environment (auto-populated)
+  errorMessage?: string  // Error message (if Error passed)
+  errorStack?: string    // Error stack trace (if Error passed)
+}
+```
+
+### Built-in Appenders
+
+#### ConsoleAppender
+
+Default appender that writes to the console:
+
+```typescript
+import { ConsoleAppender } from "@wireio/shared"
+
+const appender = new ConsoleAppender({
+  prettyPrint: true,
+  formatter: ({ level, message, category }) =>
+    `[${category}] (${level}) ${message}`
+})
+```
+
+#### AWSFirehoseAppender
+
+Streams logs to AWS Kinesis Data Firehose for centralized log aggregation:
+
+```typescript
+import { AWSFirehoseAppender, AWSFirehoseCredentialManager } from "@wireio/shared"
+
+const credManager = new AWSFirehoseCredentialManager()
+const firehoseAppender = new AWSFirehoseAppender(credManager)
+
+logManager.addAppenders(firehoseAppender)
+```
+
+**Features:**
+- Automatic credential refresh before expiration (3-minute buffer)
+- Batched record delivery (up to 10 records per batch)
+- Queue management with 10,000 record limit (oldest records dropped when exceeded)
+- Automatic retry on expired token errors
+- Event-driven credential handling via EventEmitter3
+
+**Credential Manager Events:**
+
+```typescript
+credManager.on("received", (creds) => {
+  console.log("Credentials received, stream:", creds.streamName)
+})
+
+credManager.on("expired", () => {
+  console.log("Credentials expired")
+})
+```
+
+**AWS Credentials Structure:**
+
+```typescript
+interface AWSCredentials {
+  accessKeyId: string
+  secretAccessKey: string
+  sessionToken: string
+  streamName: string      // Firehose delivery stream name
+  region: string          // AWS region
+  expiration: string      // ISO 8601 expiration timestamp
+}
+```
+
+The credential manager fetches temporary credentials from an HTTP endpoint and automatically schedules refresh before expiration.
+
+### Custom Appenders
+
+Implement the `Appender` interface:
+
+```typescript
+import { Appender, LogRecord } from "@wireio/shared"
+
+class MyCustomAppender implements Appender {
+  append(record: LogRecord): void {
+    // Send to external service, write to file, etc.
+  }
+}
+```
+
+---
+
+## Guards
+
+Type guards and assertion utilities for runtime type checking with TypeScript type narrowing.
+
+### Primitive Guards
+
+```typescript
+import {
+  isString, isNumber, isBoolean, isFunction,
+  isObject, isArray, isNil, isDefined, isPromise
+} from "@wireio/shared"
+
+if (isString(value)) {
+  // value is narrowed to string
+  console.log(value.toUpperCase())
+}
+
+if (isDefined(maybeNull)) {
+  // maybeNull is narrowed to exclude null/undefined
+}
+
+if (isPromise(result)) {
+  // result is narrowed to Promise<any>
+  await result
+}
+```
+
+### Available Guards
+
+| Guard | Type Narrowing |
+|-------|----------------|
+| `isNil(o)` | `undefined \| null` |
+| `isDefined(o)` | Excludes `undefined \| null` |
+| `isString(o)` | `string` |
+| `isNumber(o)` | `number` (excludes NaN) |
+| `isBoolean(o)` | `boolean` |
+| `isFunction(o)` | `Function` |
+| `isObject(o)` | `Object` |
+| `isArray(o)` | `Array<T>` |
+| `isPromise(o)` | `Promise<any>` |
+| `isSymbol(o)` | `Symbol` |
+| `isDate(o)` | `Date` |
+| `isPrimitive(o)` | `boolean \| string \| number` |
+
+### Assertions
+
+```typescript
+import { assert, AssertError } from "@wireio/shared"
+
+// Throws AssertError if condition is false
+assert(user !== null, "User must be defined")
+
+// With function condition
+assert(() => array.length > 0, "Array must not be empty")
+
+// Lifted assertions for reuse
+const assertPositive = assert.lift(
+  (n: number) => n > 0,
+  (n) => `Expected positive number, got ${n}`
+)
+
+assertPositive(5)   // OK
+assertPositive(-1)  // Throws AssertError
+```
+
+### Safe Value Access
+
+```typescript
+import { getValue, guard } from "@wireio/shared"
+
+// Get value with fallback on error
+const name = getValue(() => user.profile.name, "Unknown")
+
+// Execute function, swallow errors
+guard(() => riskyOperation())
+
+// With error handler
+guard(() => riskyOperation(), (err) => console.error(err))
+```
+
+---
+
+## Deferred (a `Promise` you manage)
+
+A `Deferred` is a Promise that can be resolved or rejected externally, useful for coordinating async operations.
+
+```typescript
+import { Deferred, DeferredStatus } from "@wireio/shared"
+
+// Create a deferred promise
+const deferred = new Deferred<string>()
+
+// Resolve it later
+setTimeout(() => deferred.resolve("done"), 1000)
+
+// Await the promise
+const result = await deferred.promise
+```
+
+### Deferred API
+
+```typescript
+// Create with optional existing promise to wrap
+const deferred = new Deferred<T>(existingPromise?)
+
+// The underlying promise
+deferred.promise: Promise<T>
+
+// Resolve the promise
+deferred.resolve(value?: T): void
+
+// Reject the promise
+deferred.reject(error: any): void
+
+// Cancel (prevents future resolve/reject)
+deferred.cancel(): void
+
+// Status checks
+deferred.isFulfilled(): boolean
+deferred.isRejected(): boolean
+deferred.isSettled(): boolean
+deferred.isCancelled(): boolean
+deferred.status(): DeferredStatus
+
+// Get result (throws if not settled)
+deferred.value: T
+deferred.error: Error | undefined
+```
+
+### Static Methods
+
+```typescript
+// Create an already-resolved Deferred
+const resolved = Deferred.resolve("value")
+
+// Delay utility
+await Deferred.delay(1000)  // Wait 1 second
+```
+
+### Use Cases
+
+**Timeout wrapper:**
+```typescript
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const deferred = new Deferred<T>()
+  const timer = setTimeout(() => deferred.reject(new Error("Timeout")), ms)
+
+  promise
+    .then((v) => { clearTimeout(timer); deferred.resolve(v) })
+    .catch((e) => { clearTimeout(timer); deferred.reject(e) })
+
+  return deferred.promise
+}
+```
+
+**Coordination:**
+```typescript
+class ResourceLoader {
+  private loadDeferred: Deferred<Resource> | null = null
+
+  async load(): Promise<Resource> {
+    if (this.loadDeferred) return this.loadDeferred.promise
+
+    this.loadDeferred = new Deferred()
+    try {
+      const resource = await fetchResource()
+      this.loadDeferred.resolve(resource)
+    } catch (e) {
+      this.loadDeferred.reject(e)
+    }
+    return this.loadDeferred.promise
+  }
+}
+```
+
+---
+
+## API Reference
+
+### Logging Exports
+
+```typescript
+import {
+  // Manager
+  LoggingManager,
+  getLoggingManager,
+
+  // Logger
+  Logger,
+  LoggerOptions,
+
+  // Levels
+  Level,
+  LevelKind,
+  LevelNames,
+  LevelThresholds,
+
+  // Records
+  LogRecord,
+
+  // Appenders
+  Appender,
+  ConsoleAppender,
+  DebugAppender,
+  AWSFirehoseAppender,
+
+  // Formatters
+  Formatter,
+} from "@wireio/shared"
+```
+
+### Guards Exports
+
+```typescript
+import {
+  // Primitives
+  isNil, isDefined, isString, isNumber, isBoolean,
+  isFunction, isObject, isArray, isPromise, isSymbol,
+  isDate, isPrimitive,
+
+  // Assertions
+  assert, AssertError,
+
+  // Utilities
+  getValue, guard,
+} from "@wireio/shared"
+```
+
+### Helpers Exports
+
+```typescript
+import { Deferred, DeferredStatus } from "@wireio/shared"
+```

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@wireio/shared",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "lib",
+    "README.md"
+  ],
   "type": "module",
   "types": "lib/index.d.ts",
   "module": "lib/index.js",

package/src/guards/applyTypeGuardExtras.ts

@@ -1,9 +0,0 @@
-import type { TypeGuard, TypeGuardExtras } from "./types"
-
-
-export function applyTypeGuardExtras<T>(fn:TypeGuard<T>):TypeGuardExtras<T> {
-  (
-    fn as TypeGuardExtras<T>
-  ).lift = (o:any) => () => fn(o)
-  return fn as TypeGuardExtras<T>
-}

package/src/guards/array.ts

@@ -1,5 +0,0 @@
-export function isArray(
-  o: unknown
-): o is Array<typeof o extends Array<infer T> ? T : any> {
-  return Array.isArray(o)
-}

package/src/guards/assert.ts

@@ -1,83 +0,0 @@
-import { isFunction, isString } from "./primitive.js"
-
-export interface AssertOptions {
-  logErrorsToConsole: boolean
-}
-
-export const DefaultAssertOptions:AssertOptions = {
-  logErrorsToConsole: false
-}
-
-let assertOptions:AssertOptions = {...DefaultAssertOptions}
-
-export function getAssertOptions() {
-  return {...assertOptions}
-}
-
-export function setGlobalAssertOptions(options: AssertOptions) {
-  assertOptions = {...assertOptions, ...options}
-}
-
-export class AssertError extends Error {
-  
-  
-  
-  constructor(message: string,  public readonly cause?: Error) {
-    super(message)
-  }
-}
-
-
-const assertLift:AssertLift = <T>(test: (value:T) => boolean, messageProvider: string | ((value: T) => string)) => {
-  return (nextValue: T) => {
-    const ok = test(nextValue)
-    if (!ok) {
-      const message = isFunction(messageProvider) ? messageProvider(nextValue) : messageProvider ?? "no message"
-      throw new AssertError(message)
-    }
-  }
-}
-
-export type AssertLift = <T>(test: (value:T) => boolean, message: string | ((value: T) => string)) =>
-  (nextValue: T) => void | never
-
-export interface Assert {
-  (
-    test: (() => boolean) | boolean,
-    msg?: null | ((err?: Error) => Error | string) | Error | string | undefined,
-    overrideOptions?: Partial<AssertOptions>
-  ): void | never
-  
-  lift: AssertLift
-}
-
-
-export const assert: Assert = Object.assign((
-  test: (() => boolean) | boolean,
-  msg?: null | ((err?: Error) => Error | string) | Error | string | undefined,
-  overrideOptions: Partial<AssertOptions> = {}
-): void | never => {
-  const options = {...assertOptions, ...overrideOptions}
-  let result: boolean = false
-  let error: Error = undefined
-  
-  try {
-    result = isFunction(test) ? test() : test
-  } catch (err) {
-    error = err
-    if (options.logErrorsToConsole) {
-      console.error(`Assert failed: "${test}"`, err)
-    }
-  }
-  
-  if (!result || !!error) {
-    const errOut = !msg ? (error?.message ?? "unknown") :
-      isFunction(msg) ? msg(error) :
-        msg
-    throw isString(errOut) ? new AssertError(errOut, error) : errOut
-  }
-}, {
-  lift: assertLift
-})
-
-

package/src/guards/class.ts

@@ -1,56 +0,0 @@
-/**
- * Is ES6+ class
- *
- * @see https://stackoverflow.com/questions/29093396/how-do-you-check-the-difference-between-an-ecmascript-6-class-and-function/49510834
- *
- * @param {any} value
- * @returns {boolean}
- */
-import type { ClassConstructor, TypeGuard } from "./types"
-
-export function isNativeClass <T = any>(value:any): value is ClassConstructor<T> {
-  return typeof value === 'function' && value.toString().indexOf('class') === 0
-}
-
-// Character positions
-const INDEX_OF_FUNCTION_NAME = 9  // "function X", X is at index 9
-const FIRST_UPPERCASE_INDEX_IN_ASCII = 65  // A is at index 65 in ASCII
-const LAST_UPPERCASE_INDEX_IN_ASCII = 90   // Z is at index 90 in ASCII
-
-/**
- * Is Conventional Class
- * Looks for function with capital first letter MyClass
- * First letter is the 9th character
- * If changed, isClass must also be updated
- * @param {any} value
- * @returns {boolean}
- */
-export function isConventionalClass <T = any>(value:any): value is ClassConstructor<T> {
-  if ( typeof value !== 'function' )  return false
-  const c = value.toString().charCodeAt(INDEX_OF_FUNCTION_NAME)
-  return c >= FIRST_UPPERCASE_INDEX_IN_ASCII && c <= LAST_UPPERCASE_INDEX_IN_ASCII
-}
-
-
-export function isClass<T = any>(value: any, includeConventional: boolean = true): value is ClassConstructor<T> {
-  return isNativeClass<T>(value) || (includeConventional && isConventionalClass<T>(value))
-}
-
-
-
-
-
-export function createInstanceOfGuard<T, Ctor extends ClassConstructor<T>>(ctor: Ctor): ((o: any) => o is T) {
-  return (o: any): o is T => o instanceof ctor
-}
-
-export function instanceOf<T extends {}, Ctor extends ClassConstructor<T>>(ctor: Ctor) {
-  return createInstanceOfGuard<T,Ctor>(ctor)
-} 
-
-export function createGenericGuard<T>(tester: (val:any) => val is T):TypeGuard<T>
-export function createGenericGuard<T>(type:{new():T}, tester: (val:any) => val is T):TypeGuard<T>
-export function createGenericGuard<T>(typeOrTest: ({new():T} | ((val:any) => val is T)), tester?: (val:any) => val is T) {
-  return tester as TypeGuard<T>
-}
-

package/src/guards/guard-tools.ts

@@ -1,78 +0,0 @@
-import { isNil, isPromise } from "./primitive.js"
-import type { ErrorHandler } from "./types.js"
-
-export type GuardErrorHandler = (err:Error) => void
-
-let globalErrorHandler:GuardErrorHandler | null
-
-export function setGuardErrorHandler(errorHandler:GuardErrorHandler | null = null) {
-	globalErrorHandler = errorHandler
-}
-
-export type ReturnTypeOrAny<Fn extends () => any> = (ReturnType<Fn> extends never ? unknown : ReturnType<Fn>)
-
-
-/**
- * Get a value in a guarded fashion
- * ensuring no exception
- *
- * @param fn
- * @param defaultValue
- * @returns {any}
- * @param errorHandler
- */
-export function getValue<Fn extends () => any, T extends ReturnType<Fn> >(
-	fn:Fn,
-	defaultValue: T = undefined,
-	errorHandler: ErrorHandler = globalErrorHandler
-):T extends Promise<infer T2> ? Promise<T2> : T {
-	
-	let result = null
-
-	try {
-		result = fn()
-		if (isPromise(result))
-			return result
-				.catch(err => {
-					if (errorHandler)
-						errorHandler(err)
-
-					return defaultValue
-				})
-				.then(value => isNil(value) ? defaultValue : value) as any
-	} catch (err) {
-		if (errorHandler)
-			errorHandler(err)
-	}
-
-	return isNil(result) ?
-		(defaultValue as any) : result
-}
-
-
-export type GuardFn = <Fn extends () => any, T extends ReturnType<Fn> >(fn:Fn, localErrorHandler?: GuardErrorHandler | null) => (void | Promise<void>)
-export type GuardTool = GuardFn & {
-	lift: <T>(fn:() => T, localErrorHandler?: GuardErrorHandler | null) => ((fn:() => T, localErrorHandler?: GuardErrorHandler | null) => (void | Promise<void>))
-}
-
-
-
-/**
- * Execute a function guarded from exception
- *
- * @param fn
- * @param localErrorHandler
- * @returns {(fn:()=>any)=>(fn:()=>any)=>any}
- */
-const guardFn:GuardFn = <Fn extends () => any, T extends ReturnType<Fn> >(fn:Fn, localErrorHandler: ((err: Error) => void) | null = null):void | Promise<void> => {
-	const value = getValue<Fn,T>(fn, undefined, localErrorHandler)
-	if (isPromise(value))
-		return value.then(() => undefined as void)
-	
-}
-
-export const guard: GuardTool = Object.assign(guardFn, {
-	lift: <Fn extends () => any, T extends ReturnType<Fn> >(fn:Fn, localErrorHandler?: GuardErrorHandler | null) =>
-		(fn:Fn, localErrorHandler?: GuardErrorHandler | null): (void | Promise<void>) =>
-			guardFn<Fn,T>(fn,localErrorHandler)
-})

package/src/guards/index.ts

@@ -1,7 +0,0 @@
-export * from "./class.js"
-export * from "./array.js"
-export * from "./types.js"
-export * from "./primitive.js"
-export * from "./types.js"
-export * from "./assert.js"
-export * from "./guard-tools.js"