Feature/dynamic functional context

.github/workflows/publish.yml

@@ -0,0 +1,132 @@
+name: Publish Package with Provenance
+
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: 'Package to publish'
+        required: true
+        type: choice
+        options:
+          - '@magmacomputing/tempo'
+          - '@magmacomputing/tempo-fns'
+          - '@magmacomputing/tempo-plugin-ai'
+          - '@magmacomputing/tempo-plugin-astro'
+          - '@magmacomputing/tempo-plugin-batch'
+          - '@magmacomputing/tempo-plugin-finance'
+          - '@magmacomputing/tempo-plugin-snap'
+          - '@magmacomputing/tempo-plugin-sync'
+          - 'all'
+      dry_run:
+        description: 'Dry run (simulate without uploading to registry)'
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  id-token: write # Mandatory for npm Sigstore/OIDC cryptographic provenance
+
+jobs:
+  validate-and-publish:
+    name: Publish with Provenance
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: npm
+      url: https://www.npmjs.com/org/magmacomputing
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      TZ: America/New_York
+      LANG: en_US.UTF-8
+      LC_ALL: en_US.UTF-8
+      TEMPO_LICENSE_KEY: ${{ secrets.TEMPO_LICENSE_KEY || '' }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Tempo License Key
+        run: |
+          if [ -n "$TEMPO_LICENSE_KEY" ]; then
+            LICENSE_FILE="${{ runner.temp }}/tempo.key"
+            echo "$TEMPO_LICENSE_KEY" > "$LICENSE_FILE"
+            echo "TEMPO_LICENSE_PATH=$LICENSE_FILE" >> $GITHUB_ENV
+          fi
+
+      - name: Build Monorepo Workspaces
+        run: |
+          npm run build:library
+          npm run build:tempo
+          npm run build --workspace=@magmacomputing/tempo-plugin-ai --workspace=@magmacomputing/tempo-plugin-astro --workspace=@magmacomputing/tempo-plugin-batch --workspace=@magmacomputing/tempo-plugin-finance --workspace=@magmacomputing/tempo-plugin-snap --workspace=@magmacomputing/tempo-plugin-sync --if-present
+
+      - name: Run Tests
+        run: npm run test
+
+      - name: Publish Selected Package
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          SELECTED_PKG: ${{ inputs.package }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          PROVENANCE_FLAG="--provenance --access public"
+          if [ "$DRY_RUN" = "true" ]; then
+            PROVENANCE_FLAG="$PROVENANCE_FLAG --dry-run"
+            echo "🔍 DRY RUN MODE ACTIVATED — Simulating publication..."
+          fi
+
+          WORKSPACES=(
+            "@magmacomputing/tempo"
+            "@magmacomputing/tempo-fns"
+            "@magmacomputing/tempo-plugin-ai"
+            "@magmacomputing/tempo-plugin-astro"
+            "@magmacomputing/tempo-plugin-batch"
+            "@magmacomputing/tempo-plugin-finance"
+            "@magmacomputing/tempo-plugin-snap"
+            "@magmacomputing/tempo-plugin-sync"
+          )
+
+          publish_workspace() {
+            local pkg="$1"
+            local ver
+            ver=$(npm pkg get version --workspace="$pkg" | awk '{print $NF}' | tr -d '"')
+            echo "Checking $pkg@$ver on npm..."
+
+            if [ "$DRY_RUN" != "true" ] && npm view "$pkg@$ver" version >/dev/null 2>&1; then
+              echo "⏩ $pkg@$ver is already published on npm. Skipping to support partial release recovery."
+              return 0
+            fi
+
+            echo "🚀 Publishing $pkg@$ver..."
+            npm publish --workspace="$pkg" $PROVENANCE_FLAG
+          }
+
+          if [ "$SELECTED_PKG" = "all" ]; then
+            echo "🔎 Preflighting all 8 package versions..."
+            for pkg in "${WORKSPACES[@]}"; do
+              ver=$(npm pkg get version --workspace="$pkg" | awk '{print $NF}' | tr -d '"')
+              echo "  - $pkg: $ver"
+              if [ -z "$ver" ] || [ "$ver" = "null" ]; then
+                echo "❌ Failed to resolve version for $pkg"
+                exit 1
+              fi
+            done
+
+            echo "🚀 Publishing all workspaces..."
+            for pkg in "${WORKSPACES[@]}"; do
+              publish_workspace "$pkg"
+            done
+          else
+            publish_workspace "$SELECTED_PKG"
+          fi

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "private": true,
   "engines": {
     "node": ">=20.0.0"

packages/library/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.12.0] - 2026-08-19
+
+### Added
+- **Dynamic Evaluation Utilities (`evaluation.library`)**: Added `#library/evaluation.library.js` containing `evaluate(...values)`, `evaluateAsync(...values)`, `evaluateConfig(config)`, and `evaluateConfigAsync(config)`. Supports variadic synchronous and asynchronous value/supplier evaluation with lazy, short-circuiting coalescing.
+- **Dynamic Property Proxy (`proxy.library`)**: Added `dynamicProxy(target)` for zero-overhead dynamic property proxying with on-access evaluation of function-valued properties on the target object.
+- **Standardized Evaluation Types (`type.library`)**: Added `Evaluable<T>`, `AsyncEvaluable<T>`, `EvaluableRecord<T>`, `AsyncEvaluableRecord<T>`, `Evaluated<T>`, `AsyncEvaluated<T>`, and unified `Resolved<T>` on top of `Awaited<T>`.
+
 ## [3.11.1] - 2026-08-06
 
 ### Added

packages/library/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/library",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "Shared utility library for Tempo",
   "author": "Magma Computing Solutions",
   "license": "MIT",

packages/library/src/common.index.ts

@@ -10,6 +10,7 @@ export * from './common/cipher.library.js';
 export * from './common/class.library.js';
 export * from './common/coercion.library.js';
 export * from './common/enumerate.library.js';
+export * from './common/evaluation.library.js';
 export * from './common/function.library.js';
 export * from './common/international.library.js';
 export * from './common/logger.class.js';

packages/library/src/common/evaluation.library.ts

@@ -0,0 +1,117 @@
+import { isFunction, isNullish, isObject, isPromise } from '#library/assertion.library.js';
+import type { Evaluable, AsyncEvaluable, Evaluated, AsyncEvaluated } from '#library/type.library.js';
+
+/**
+ * Evaluates candidate synchronous scalars or supplier functions in order, returning the first defined result (lazy coalesce).
+ * If a candidate is a function, it is invoked with zero arguments.
+ * Candidates after the first defined value are never evaluated (short-circuiting).
+ * If all candidates evaluate to undefined, returns undefined.
+ * Any exception thrown by an evaluated supplier function bubbles directly to the caller.
+ * 
+ * @param values - One or more scalars or synchronous supplier functions to evaluate in sequence
+ * @returns The first resolved defined value, or undefined if none resolved
+ * @example
+ * ```ts
+ * evaluate(42); // 42
+ * evaluate(() => 'UTC'); // 'UTC'
+ * evaluate(undefined, 'fallback'); // 'fallback'
+ * evaluate(undefined, () => undefined, () => 'dynamic-fallback', 'final'); // 'dynamic-fallback'
+ * ```
+ */
+export function evaluate<T>(first: Evaluable<T> | undefined, fallback: Evaluable<T>, ...rest: Evaluable<T>[]): T;
+export function evaluate<T>(...values: (Evaluable<T> | undefined)[]): T | undefined;
+export function evaluate<T>(...values: (Evaluable<T> | undefined)[]): T | undefined {
+	for (const val of values) {
+		const resolved = isFunction(val) ? (val as () => T)() : val;
+		if (resolved !== undefined) return resolved as T;
+	}
+	return undefined;
+}
+
+/**
+ * Evaluates candidate synchronous or asynchronous scalars, Promises, or supplier functions in order, returning the first defined result (async lazy coalesce).
+ * Supplier functions represent deferred asynchronous work and are invoked lazily only when reached during evaluation.
+ * Rejection handlers are attached upfront to direct Promise candidates to prevent unobserved rejections if iteration short-circuits on an earlier defined candidate.
+ * If all candidates evaluate to undefined, returns undefined.
+ * Any exception or rejection thrown by an evaluated candidate bubbles directly to the caller.
+ * 
+ * @param values - One or more scalars, Promises, or async supplier functions to evaluate in sequence
+ * @returns A Promise resolving to the first defined value, or undefined if none resolved
+ * @example
+ * ```ts
+ * await evaluateAsync('apiKey123'); // 'apiKey123'
+ * await evaluateAsync(undefined, async () => fetchSecret(), 'defaultKey'); // 'secret'
+ * ```
+ */
+export function evaluateAsync<T>(first: AsyncEvaluable<T> | undefined, fallback: AsyncEvaluable<T>, ...rest: AsyncEvaluable<T>[]): Promise<T>;
+export function evaluateAsync<T>(...values: (AsyncEvaluable<T> | undefined)[]): Promise<T | undefined>;
+export async function evaluateAsync<T>(...values: (AsyncEvaluable<T> | undefined)[]): Promise<T | undefined> {
+	for (const val of values)
+		if (!isFunction(val) && isFunction((val as any)?.then))
+			(val as PromiseLike<any>).then(undefined, () => {});
+
+	for (const val of values) {
+		const resolved = isFunction(val) ? await (val as () => T | Promise<T>)() : await val;
+		if (resolved !== undefined) return resolved as T;
+	}
+	return undefined;
+}
+
+/**
+ * Resolves all top-level properties of a configuration object synchronously.
+ * For each property whose value is a function, executes the function and sets the property to its return value.
+ * 
+ * @param config - The configuration object to evaluate
+ * @returns A new object with all properties synchronously resolved
+ * @example
+ * ```ts
+ * const evaluated = evaluateConfig({
+ *   timeZone: () => 'America/New_York',
+ *   locale: 'en-US'
+ * });
+ * // { timeZone: 'America/New_York', locale: 'en-US' }
+ * ```
+ */
+export function evaluateConfig<T extends object>(config: T): Evaluated<T> {
+	if (isNullish(config) || !isObject(config)) return config as any;
+	const result = { ...config } as any;
+
+	for (const key of Object.keys(config) as (keyof T)[]) {
+		const val = config[key];
+		result[key] = isFunction(val) ? (val as () => any)() : val;
+	}
+
+	return result;
+}
+
+/**
+ * Resolves all top-level properties of a configuration object asynchronously.
+ * For each property whose value is a function or Promise, executes/awaits the value and sets the property.
+ * 
+ * @param config - The configuration object to evaluate
+ * @returns A Promise resolving to a new object with all properties resolved
+ * @example
+ * ```ts
+ * const evaluated = await evaluateConfigAsync({
+ *   key: async () => fetchKey(),
+ *   url: 'https://api.openai.com/v1'
+ * });
+ * // { key: 'sk-...', url: 'https://api.openai.com/v1' }
+ * ```
+ */
+export async function evaluateConfigAsync<T extends object>(config: T): Promise<AsyncEvaluated<T>> {
+	if (isNullish(config) || !isObject(config)) return config as any;
+	const result = { ...config } as any;
+	const keys = Object.keys(config) as (keyof T)[];
+	const values = await Promise.all(
+		keys.map(key => {
+			const val = config[key];
+			return isFunction(val) ? (val as () => any)() : val;
+		})
+	);
+
+	for (let i = 0; i < keys.length; i++)
+		result[keys[i]] = values[i];
+
+	return result;
+}

packages/library/src/common/proxy.library.ts

@@ -2,8 +2,8 @@ import { sym } from '#library/symbol.library.js';
 import { allObject } from '#library/reflection.library.js';
 import { deepFreeze } from '#library/utility.library.js';
 import { unwrap } from '#library/primitive.library.js';
-import { isString, isFunction, isSymbol, isDefined, isNumber } from '#library/assertion.library.js';
-import { registerType, type Constructor } from '#library/type.library.js';
+import { isString, isFunction, isSymbol, isDefined, isNumber, isObject } from '#library/assertion.library.js';
+import { registerType, type Constructor, type Evaluated } from '#library/type.library.js';
 
 const boundMethodCache = new WeakMap<Function, WeakMap<object, Function>>();
 
@@ -255,3 +255,47 @@ export function indexedArray<T extends object>(
 			: undefined;
 	}, readonly) as any;
 }
+
+/**
+ * Wraps an object in a dynamic evaluation Proxy where any property that is a function/supplier
+ * is transparently invoked upon read access.
+ * Non-function properties and symbol traps are forwarded as-is.
+ * 
+ * @param target - The object containing dynamic properties or suppliers
+ * @returns A Proxy wrapping the target where property reads automatically resolve functions
+ * @example
+ * ```ts
+ * const userContext = {
+ *   timeZone: () => currentSession.tz,
+ *   locale: 'en-US'
+ * };
+ * const proxy = dynamicProxy(userContext);
+ * proxy.timeZone; // Returns dynamic currentSession.tz
+ * proxy.locale;   // 'en-US'
+ * ```
+ */
+export function dynamicProxy<T extends object>(target: T): Evaluated<T> {
+	if (!isObject(target)) return target as any;
+	return new Proxy(unwrap(target), {
+		get(t, k, r) {
+			if (k === sym.$Target) return t;
+			const val = Reflect.get(t, k, r);
+			if (!isFunction(val) || isSymbol(k) || k === 'constructor')
+				return val;
+			const desc = Reflect.getOwnPropertyDescriptor(t, k);
+			if (desc && !desc.configurable && !desc.writable)
+				return val;
+			return (val as () => any)();
+		},
+		has(t, k) {
+			return Reflect.has(t, k);
+		},
+		ownKeys(t) {
+			return Reflect.ownKeys(t);
+		},
+		getOwnPropertyDescriptor(t, k) {
+			return Reflect.getOwnPropertyDescriptor(t, k);
+		},
+	}) as any;
+}
+