Perf/lazy delegator

package.json

@@ -12,18 +12,23 @@
   "scripts": {
     "test": "npm run test --workspaces --if-present",
     "build": "tsc -b",
+    "build:tempo": "npm run build --workspace=@magmacomputing/tempo",
+    "build:library": "npm run build --workspace=@magmacomputing/library",
     "clean": "tsc -b --clean",
     "release": "release-it",
-    "release:tempo": "npm run build --workspace=@magma/tempo && cd packages/tempo && bash resolve-self.sh && npm publish",
-    "version:patch": "npm version patch -w @magma/tempo -w @magma/library --no-git-tag-version",
-    "version:minor": "npm version minor -w @magma/tempo -w @magma/library --no-git-tag-version",
-    "version:major": "npm version major -w @magma/tempo -w @magma/library --no-git-tag-version",
-    "repl": "npm run repl --workspace=@magma/tempo"
+    "release:tempo": "npm run build --workspace=@magmacomputing/tempo && npm run publish --workspace=@magmacomputing/tempo",
+    "version:patch": "npm version patch -w @magmacomputing/tempo -w @magmacomputing/library --no-git-tag-version",
+    "version:minor": "npm version minor -w @magmacomputing/tempo -w @magmacomputing/library --no-git-tag-version",
+    "version:major": "npm version major -w @magmacomputing/tempo -w @magmacomputing/library --no-git-tag-version",
+    "repl": "npm run repl --workspace=@magmacomputing/tempo"
   },
   "devDependencies": {
     "@js-temporal/polyfill": "^0.5.1",
     "@release-it/keep-a-changelog": "^7.0.1",
     "@rollup/plugin-node-resolve": "^16.0.3",
+    "@types/google.maps": "^3.58.1",
+    "@types/hammerjs": "^2.0.46",
+    "@types/jquery": "^4.0.0",
     "@types/node": "^25.5.0",
     "@vitest/ui": "^4.0.18",
     "release-it": "^19.2.4",
@@ -35,4 +40,4 @@
   "dependencies": {
     "@scarf/scarf": "^1.4.0"
   }
-}
+}

packages/library/doc/browser/api.md

@@ -0,0 +1,45 @@
+# Browser API Documentation
+
+This section details the browser-specific utilities and API methods.
+
+## WebStore (`webstore.class.ts`)
+
+A wrapper around `localStorage` and `sessionStorage` that supports automatic serialization and merging.
+
+### `WebStore.local` / `WebStore.session`
+Static accessors for default `WebStore` instances.
+
+### `get<T>(key: PropertyKey, dflt?: T): T | null`
+Retrieves and deserializes a value from storage.
+
+### `set(key: PropertyKey, obj: unknown, opt?: { merge: boolean }): WebStore`
+Saves a value to storage. Supports merging for Object, Array, Map, and Set.
+
+### `del(...keys: PropertyKey[]): WebStore`
+Removes specified keys from storage.
+
+## Tapper (`tapper.class.ts`)
+
+A wrapper around HammerJS for managing single, double, and triple tap events.
+
+### `new Tapper(elm: string, ...setup: (Callback | Tuple)[])`
+Initializes tapper on an element with provided callbacks.
+
+### `on(...events: (Callback | Tuple)[]): Tapper`
+Adds event listeners for `SingleTap`, `DoubleTap`, or `TripleTap`.
+
+### `off(...events: Tapper.EVENT[]): Tapper`
+Removes specific event listeners.
+
+## Mapper (`mapper.library.ts`)
+
+Utilities for geolocation and Google Maps integration.
+
+### `geoLocation(opts?: MapOpts): Promise<GeolocationPosition>`
+Attempts to get the current device position. Stashes results to avoid redundant calls.
+
+### `mapQuery(coords?: GeocoderRequest, opts?: MapOpts): Promise<GeocoderResponse>`
+Queries Google Maps API for geocoding information.
+
+### `mapAddress(coords?: GeocoderRequest, opts?: MapOpts): Promise<Record<string, string>>`
+Returns a best-guess formatted address for the given coordinates.

packages/library/doc/browser/types.md

@@ -0,0 +1,32 @@
+# Browser Interface and Type Definitions
+
+This document details the types and interfaces used by the browser-specific API.
+
+## Storage Types (`webstore.class.ts`)
+
+### `STORAGE`
+Enum-like object for identifying storage type: `'local' | 'session'`.
+
+## Tapper Types (`tapper.class.ts`)
+
+### `Tapper.EVENT`
+Enum for supported tap events:
+- `SingleTap`: `'singleTap'`
+- `DoubleTap`: `'doubleTap'`
+- `TripleTap`: `'tripleTap'`
+
+### `Tapper.Callback`
+A function signature for tap event handlers: `(evt: HammerInput) => void`.
+
+### `Tapper.Tuple`
+A convenience type for registering events: `[Tapper.EVENT, Tapper.Callback]`.
+
+## Mapper Types (`mapper.library.ts`)
+
+### `MapOpts`
+Options for mapping functions:
+- `catch?: boolean` (Interprets Promise reject as resolve)
+- `debug?: boolean` (Enables logging)
+
+### `MapStore`
+Internal interface for cached geolocation and geocoder results.

packages/library/doc/common/api.md

@@ -0,0 +1,56 @@
+# Common API Documentation
+
+This section covers the core utility functions available across all environments (Browser and Node.js).
+
+## String Utilities (`string.library.ts`)
+
+### `trimAll(str: string | number, pat?: RegExp): string`
+Removes standard control characters (tab, line-feed, carriage-return) and trims redundant spaces.
+
+### `toProperCase<T extends string>(...str: T[]): T`
+Capitalizes the first letter of every word in the provided string(s).
+
+### `toCamelCase<T extends string>(sentence: T): T`
+Converts a string to camelCase.
+
+### `sprintf(fmt: string, ...msg: any[]): string`
+Provides `sprintf`-style formatting. Supports `%s` and `%j` (JSON) placeholders.
+
+### `plural(val: any, word: string, plural?: string): string`
+Applies a plural suffix if the value is not 1 or -1.
+
+### `pad(nbr: any, len?: number, fill?: string | number): string`
+Pads a string or number on the left to reach the specified length.
+
+## Array Utilities (`array.library.ts`)
+
+### `sortInsert<T, K extends keyof T>(arr: T[], val: T, key?: K): T[]`
+Inserts a value into a sorted array at its correct position (mutates the array).
+
+### `sortBy<T>(...keys: (PropertyKey | SortBy)[]): (left: T, right: T) => number`
+Returns a sort function for ordering objects by multiple keys.
+
+### `byKey<T>(arr: T[], ...keys: (keyof T)[]): Record<PropertyKey, T[]>`
+Groups an array of objects by one or more keys.
+
+### `distinct<T>(arr: T[]): T[]`
+Returns a new array with unique elements.
+
+## Object Utilities (`object.library.ts`)
+
+### `extract<T>(obj: any, path: string | number, dflt?: T): T`
+Retrieves a nested value from an object using a dot-notated path (e.g., `user.profile[0].name`).
+
+### `isEqual(obj1: any, obj2: any): boolean`
+Deeply compares two objects for equality.
+
+### `pick<T, K extends string>(obj: T, ...keys: K[]): Partial<T>`
+Creates a subset of an object containing only the specified keys.
+
+## Serialization Utilities (`serialize.library.ts`)
+
+### `stringify<T>(obj: T): string`
+A robust version of `JSON.stringify` that handles `BigInt`, `Set`, `Map`, `Symbol`, and `Undefined`.
+
+### `objectify<T>(str: any, sentinel?: Function): T`
+Rebuilds an object from a string generated by `stringify`.

packages/library/doc/common/types.md

@@ -0,0 +1,49 @@
+# Common Interface and Type Definitions
+
+This document details the shared types and interfaces used throughout the library's common utilities.
+
+## Core Type Guards
+
+### `isPrimitive(obj?: unknown): obj is Primitive`
+Generic check for primitive types.
+
+### `isDefined<T>(obj: T): obj is NonNullable<T>`
+Returns true if the value is not `null`, `undefined`, or `void`.
+
+### `isEmpty<T>(obj?: T): boolean`
+Returns true if an object, array, set, or map has no values, or if a string is empty, or a number is `NaN`.
+
+## Utility Types
+
+### `Primitive`
+A union of `string | number | bigint | boolean | symbol | void | undefined | null`.
+
+### `Nullable<T>` / `Nullish`
+`Nullable<T>` is a generic for `T | null`.  
+`Nullish` is the bottom-value union: `null | undefined | void`.
+
+### `Property<T>`
+A generic record: `Record<PropertyKey, T>`.
+
+### `TypeValue<T>`
+A structured type representation: `{ type: Type, value: T }`.
+
+### `Type`
+A union of all supported types including `'String'`, `'Number'`, `'BigInt'`, `'Object'`, `'Array'`, `'Date'`, `'Map'`, `'Set'`, `'EnumIFY'`, `'Pledge'`, `'Tempo'`, etc.
+
+## Advanced Types
+
+### `Entry<T>` / `Entries<T>`
+Strongly typed replacements for `Object.entries`.
+
+### `Secure<T>`
+Deeply `readonly` version of an object or array.
+
+### `Branded<T, B>`
+Creates a branded type for nominal typing.
+
+### `IntRange<Lower, Upper>`
+Defines a numeric range (inclusive).
+
+### `MaxLength<T, Max>` / `MinLength<T, Min>`
+Type-level string length constraints.

packages/library/doc/server/api.md

@@ -0,0 +1,40 @@
+# Server API Documentation
+
+This section details the server-side utilities and API methods.
+
+## File Utility (`file.library.ts`)
+
+Static class for file system operations using `node:fs`.
+
+### `File.read(file: string): Promise<any>`
+Reads a file from the temporary directory. Coerces the result to a number if numeric.
+
+### `File.write(file: string, doc: any): Promise<any>`
+Writes a document to the temporary directory.
+
+### `File.exist(file: string): Promise<boolean>`
+Checks if a file exists in the temporary directory.
+
+### `File.remove(path: string): Promise<void>`
+Synchronously removes a file from the temporary directory.
+
+## Request Utilities (`request.library.ts`)
+
+### `httpRequest<T>(url: string | URL, init?: RequestInit, config?: Config): Promise<T>`
+Standardized JSON fetch request with a default 2-second timeout and error handling.
+
+### `headRequest(url: string | URL): Promise<{ status: number, headers: Headers }>`
+Performs a `HEAD` request to verify resource existence without downloading content.
+
+## Buffer Utilities (`buffer.library.ts`)
+
+### `encode64(str: any): string`
+Encodes any value (after stringification) to Base64.
+
+### `decode64<T>(str: string): T`
+Decodes a Base64 string and objectifies the result.
+
+## Auth Utilities (`auth.library.ts`)
+
+### `decodeJWT(token: string): any`
+Decodes the payload of a JSON Web Token (JWT).

packages/library/doc/server/types.md

@@ -0,0 +1,27 @@
+# Server Interface and Type Definitions
+
+This document details the types and interfaces used by the server-side API.
+
+## Request Types (`request.library.ts`)
+
+### `HTTP`
+Common HTTP status codes used in requests:
+- `Ok`: 200
+- `PermRedirect`: 301
+- `TempRedirect`: 302
+- `BadRequest`: 400
+- `Unauthorised`: 401
+- `Forbidden`: 403
+
+### `METHOD`
+Standard HTTP methods:
+- `Head`: 'HEAD'
+- `Get`: 'GET'
+- `Put`: 'PUT'
+- `Delete`: 'DELETE'
+- `Post`: 'POST'
+
+### `Config`
+Optional configuration for `httpRequest`:
+- `timeout?: number` (Defaults to 2 seconds)
+- `prefix?: string` (Optional response wrapper prefix)