@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/shared/src/evaluator/std/async.ts

@@ -0,0 +1,210 @@
+/**
+ * Async Module Runtime Evaluators
+ *
+ * Runtime implementations for async/* operators.
+ * Provides functions for handling async operations, delays, and timing.
+ *
+ * @packageDocumentation
+ */
+
+import type { SExpr } from '../types/expression.js';
+import type { EvaluationContext } from '../context.js';
+
+type EvalFn = (expr: SExpr, ctx: EvaluationContext) => unknown;
+
+// Debounce timers keyed by event name
+const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+// Throttle timestamps keyed by event name
+const throttleTimestamps = new Map<string, number>();
+
+/**
+ * async/delay - Wait for specified milliseconds
+ */
+export async function evalAsyncDelay(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): Promise<void> {
+  const ms = evaluate(args[0], ctx) as number;
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * async/timeout - Add timeout to an effect
+ */
+export async function evalAsyncTimeout(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): Promise<unknown> {
+  const effect = args[0];
+  const ms = evaluate(args[1], ctx) as number;
+
+  return Promise.race([
+    Promise.resolve().then(() => evaluate(effect, ctx)),
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error('Timeout exceeded')), ms)
+    ),
+  ]);
+}
+
+/**
+ * async/debounce - Debounce an event (wait for pause in events)
+ */
+export function evalAsyncDebounce(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): void {
+  const event = evaluate(args[0], ctx) as string;
+  const ms = evaluate(args[1], ctx) as number;
+
+  // Clear existing timer if any
+  const existingTimer = debounceTimers.get(event);
+  if (existingTimer) {
+    clearTimeout(existingTimer);
+  }
+
+  // Set new timer
+  const timer = setTimeout(() => {
+    debounceTimers.delete(event);
+    // Emit the event
+    ctx.emit?.(event);
+  }, ms);
+
+  debounceTimers.set(event, timer);
+}
+
+/**
+ * async/throttle - Throttle an event (emit at most once per interval)
+ */
+export function evalAsyncThrottle(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): void {
+  const event = evaluate(args[0], ctx) as string;
+  const ms = evaluate(args[1], ctx) as number;
+
+  const now = Date.now();
+  const lastTimestamp = throttleTimestamps.get(event) ?? 0;
+
+  if (now - lastTimestamp >= ms) {
+    throttleTimestamps.set(event, now);
+    ctx.emit?.(event);
+  }
+}
+
+/**
+ * async/retry - Retry an effect with configurable backoff
+ */
+export async function evalAsyncRetry(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): Promise<unknown> {
+  const effect = args[0];
+  const opts = evaluate(args[1], ctx) as {
+    attempts?: number;
+    backoff?: 'fixed' | 'linear' | 'exponential';
+    baseDelay?: number;
+  };
+
+  const attempts = opts?.attempts ?? 3;
+  const backoff = opts?.backoff ?? 'exponential';
+  const baseDelay = opts?.baseDelay ?? 1000;
+
+  let lastError: unknown;
+
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await Promise.resolve().then(() => evaluate(effect, ctx));
+    } catch (error) {
+      lastError = error;
+
+      if (i < attempts - 1) {
+        // Calculate delay based on backoff strategy
+        let delay: number;
+        switch (backoff) {
+          case 'fixed':
+            delay = baseDelay;
+            break;
+          case 'linear':
+            delay = baseDelay * (i + 1);
+            break;
+          case 'exponential':
+          default:
+            delay = baseDelay * Math.pow(2, i);
+            break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * async/race - Execute effects in parallel, return first to complete
+ */
+export async function evalAsyncRace(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): Promise<unknown> {
+  const promises = args.map((effect) =>
+    Promise.resolve().then(() => evaluate(effect, ctx))
+  );
+  return Promise.race(promises);
+}
+
+/**
+ * async/all - Execute effects in parallel, wait for all to complete
+ */
+export async function evalAsyncAll(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): Promise<unknown[]> {
+  const promises = args.map((effect) =>
+    Promise.resolve().then(() => evaluate(effect, ctx))
+  );
+  return Promise.all(promises);
+}
+
+/**
+ * async/sequence - Execute effects in sequence (one after another)
+ */
+export async function evalAsyncSequence(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): Promise<unknown[]> {
+  const results: unknown[] = [];
+
+  for (const effect of args) {
+    const result = await Promise.resolve().then(() => evaluate(effect, ctx));
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Clear debounce timers (for testing/cleanup)
+ */
+export function clearDebounceTimers(): void {
+  for (const timer of debounceTimers.values()) {
+    clearTimeout(timer);
+  }
+  debounceTimers.clear();
+}
+
+/**
+ * Clear throttle timestamps (for testing/cleanup)
+ */
+export function clearThrottleTimestamps(): void {
+  throttleTimestamps.clear();
+}

package/shells/typescript-shell/packages/shared/src/evaluator/std/format.ts

@@ -0,0 +1,224 @@
+/**
+ * Format Module Runtime Evaluators
+ *
+ * Runtime implementations for format/* operators.
+ * Provides formatting functions for numbers, currencies, and display values.
+ *
+ * @packageDocumentation
+ */
+
+import type { SExpr } from '../types/expression.js';
+import type { EvaluationContext } from '../context.js';
+
+type EvalFn = (expr: SExpr, ctx: EvaluationContext) => unknown;
+
+/**
+ * format/number - Format number with locale-aware separators
+ */
+export function evalFormatNumber(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const n = evaluate(args[0], ctx) as number;
+  const opts = args.length > 1 ? (evaluate(args[1], ctx) as { decimals?: number; locale?: string }) : {};
+
+  const locale = opts?.locale ?? 'en-US';
+  const options: Intl.NumberFormatOptions = {};
+
+  if (opts?.decimals !== undefined) {
+    options.minimumFractionDigits = opts.decimals;
+    options.maximumFractionDigits = opts.decimals;
+  }
+
+  return new Intl.NumberFormat(locale, options).format(n);
+}
+
+/**
+ * format/currency - Format as currency
+ */
+export function evalFormatCurrency(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const n = evaluate(args[0], ctx) as number;
+  const currency = evaluate(args[1], ctx) as string;
+  const locale = args.length > 2 ? (evaluate(args[2], ctx) as string) : 'en-US';
+
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: currency,
+  }).format(n);
+}
+
+/**
+ * format/percent - Format as percentage
+ */
+export function evalFormatPercent(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const n = evaluate(args[0], ctx) as number;
+  const decimals = args.length > 1 ? (evaluate(args[1], ctx) as number) : 0;
+
+  return new Intl.NumberFormat('en-US', {
+    style: 'percent',
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(n);
+}
+
+/**
+ * format/bytes - Format bytes as human-readable size
+ */
+export function evalFormatBytes(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const bytes = evaluate(args[0], ctx) as number;
+
+  if (bytes === 0) return '0 B';
+
+  const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+  const k = 1024;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  const value = bytes / Math.pow(k, i);
+  // Use different precision rules
+  if (i === 0) {
+    return `${bytes} B`;
+  }
+  // Round values >= 10, or use 1 decimal for smaller values
+  // Also remove .0 for whole numbers
+  let formatted: string;
+  if (value >= 10) {
+    formatted = String(Math.round(value));
+  } else if (Number.isInteger(value)) {
+    formatted = String(value);
+  } else {
+    formatted = value.toFixed(1);
+  }
+
+  return `${formatted} ${units[i]}`;
+}
+
+/**
+ * format/ordinal - Format number as ordinal (1st, 2nd, 3rd)
+ */
+export function evalFormatOrdinal(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const n = evaluate(args[0], ctx) as number;
+
+  const absN = Math.abs(n);
+  const lastDigit = absN % 10;
+  const lastTwoDigits = absN % 100;
+
+  let suffix: string;
+  if (lastTwoDigits >= 11 && lastTwoDigits <= 13) {
+    suffix = 'th';
+  } else if (lastDigit === 1) {
+    suffix = 'st';
+  } else if (lastDigit === 2) {
+    suffix = 'nd';
+  } else if (lastDigit === 3) {
+    suffix = 'rd';
+  } else {
+    suffix = 'th';
+  }
+
+  return `${n}${suffix}`;
+}
+
+/**
+ * format/plural - Format count with singular/plural word
+ */
+export function evalFormatPlural(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const n = evaluate(args[0], ctx) as number;
+  const singular = evaluate(args[1], ctx) as string;
+  const plural = evaluate(args[2], ctx) as string;
+
+  return `${n} ${Math.abs(n) === 1 ? singular : plural}`;
+}
+
+/**
+ * format/list - Format array as natural language list
+ */
+export function evalFormatList(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const arr = evaluate(args[0], ctx) as string[];
+  const style = args.length > 1 ? (evaluate(args[1], ctx) as 'and' | 'or') : 'and';
+
+  if (!arr || arr.length === 0) return '';
+  if (arr.length === 1) return arr[0];
+  if (arr.length === 2) return `${arr[0]} ${style} ${arr[1]}`;
+
+  const last = arr[arr.length - 1];
+  const rest = arr.slice(0, -1);
+  return `${rest.join(', ')}, ${style} ${last}`;
+}
+
+/**
+ * format/phone - Format phone number
+ */
+export function evalFormatPhone(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const str = evaluate(args[0], ctx) as string;
+  const format = args.length > 1 ? (evaluate(args[1], ctx) as string) : 'US';
+
+  // Extract only digits
+  const digits = str?.replace(/\D/g, '') ?? '';
+
+  if (format === 'US' && digits.length === 10) {
+    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+  }
+
+  if (format === 'US' && digits.length === 11 && digits[0] === '1') {
+    return `+1 (${digits.slice(1, 4)}) ${digits.slice(4, 7)}-${digits.slice(7)}`;
+  }
+
+  // Default: group into chunks of 3-4
+  if (digits.length >= 10) {
+    return `${digits.slice(0, 3)}-${digits.slice(3, 6)}-${digits.slice(6)}`;
+  }
+
+  return str;
+}
+
+/**
+ * format/creditCard - Format credit card with masked digits
+ */
+export function evalFormatCreditCard(
+  args: SExpr[],
+  evaluate: EvalFn,
+  ctx: EvaluationContext
+): string {
+  const str = evaluate(args[0], ctx) as string;
+
+  const digits = str?.replace(/\D/g, '') ?? '';
+
+  if (digits.length < 4) return str;
+
+  // Show only last 4 digits
+  const lastFour = digits.slice(-4);
+  const masked = '•'.repeat(digits.length - 4);
+
+  // Format in groups of 4
+  const combined = masked + lastFour;
+  return combined.match(/.{1,4}/g)?.join(' ') ?? combined;
+}

package/shells/typescript-shell/packages/shared/src/evaluator/std/index.ts

@@ -0,0 +1,206 @@
+/**
+ * Standard Library Runtime Evaluators
+ *
+ * Exports all std/* operator implementations.
+ *
+ * @packageDocumentation
+ */
+
+// Math operators
+export {
+  evalMathAbs,
+  evalMathMin,
+  evalMathMax,
+  evalMathClamp,
+  evalMathFloor,
+  evalMathCeil,
+  evalMathRound,
+  evalMathPow,
+  evalMathSqrt,
+  evalMathMod,
+  evalMathSign,
+  evalMathLerp,
+  evalMathMap,
+  evalMathRandom,
+  evalMathRandomInt,
+  evalMathDefault,
+} from './math.js';
+
+// String operators
+export {
+  evalStrLen,
+  evalStrUpper,
+  evalStrLower,
+  evalStrTrim,
+  evalStrTrimStart,
+  evalStrTrimEnd,
+  evalStrSplit,
+  evalStrJoin,
+  evalStrSlice,
+  evalStrReplace,
+  evalStrReplaceAll,
+  evalStrIncludes,
+  evalStrStartsWith,
+  evalStrEndsWith,
+  evalStrPadStart,
+  evalStrPadEnd,
+  evalStrRepeat,
+  evalStrReverse,
+  evalStrCapitalize,
+  evalStrTitleCase,
+  evalStrCamelCase,
+  evalStrKebabCase,
+  evalStrSnakeCase,
+  evalStrDefault,
+  evalStrTemplate,
+  evalStrTruncate,
+} from './str.js';
+
+// Array operators
+export {
+  evalArrayLen,
+  evalArrayEmpty,
+  evalArrayFirst,
+  evalArrayLast,
+  evalArrayNth,
+  evalArraySlice,
+  evalArrayConcat,
+  evalArrayAppend,
+  evalArrayPrepend,
+  evalArrayInsert,
+  evalArrayRemove,
+  evalArrayRemoveItem,
+  evalArrayReverse,
+  evalArraySort,
+  evalArrayShuffle,
+  evalArrayUnique,
+  evalArrayFlatten,
+  evalArrayZip,
+  evalArrayIncludes,
+  evalArrayIndexOf,
+  evalArrayFind,
+  evalArrayFindIndex,
+  evalArrayFilter,
+  evalArrayReject,
+  evalArrayMap,
+  evalArrayReduce,
+  evalArrayEvery,
+  evalArraySome,
+  evalArrayCount,
+  evalArraySum,
+  evalArrayAvg,
+  evalArrayMin,
+  evalArrayMax,
+  evalArrayGroupBy,
+  evalArrayPartition,
+  evalArrayTake,
+  evalArrayDrop,
+  evalArrayTakeLast,
+  evalArrayDropLast,
+} from './array.js';
+
+// Object operators
+export {
+  evalObjectKeys,
+  evalObjectValues,
+  evalObjectEntries,
+  evalObjectFromEntries,
+  evalObjectGet,
+  evalObjectSet,
+  evalObjectHas,
+  evalObjectMerge,
+  evalObjectDeepMerge,
+  evalObjectPick,
+  evalObjectOmit,
+  evalObjectMapValues,
+  evalObjectMapKeys,
+  evalObjectFilter,
+  evalObjectEmpty,
+  evalObjectEquals,
+  evalObjectClone,
+  evalObjectDeepClone,
+  evalPath,
+} from './object.js';
+
+// Validate operators
+export {
+  evalValidateRequired,
+  evalValidateString,
+  evalValidateNumber,
+  evalValidateBoolean,
+  evalValidateArray,
+  evalValidateObject,
+  evalValidateEmail,
+  evalValidateUrl,
+  evalValidateUuid,
+  evalValidatePhone,
+  evalValidateCreditCard,
+  evalValidateDate,
+  evalValidateMinLength,
+  evalValidateMaxLength,
+  evalValidateLength,
+  evalValidateMin,
+  evalValidateMax,
+  evalValidateRange,
+  evalValidatePattern,
+  evalValidateOneOf,
+  evalValidateNoneOf,
+  evalValidateEquals,
+  evalValidateCheck,
+} from './validate.js';
+
+// Time operators
+export {
+  evalTimeNow,
+  evalTimeToday,
+  evalTimeParse,
+  evalTimeFormat,
+  evalTimeYear,
+  evalTimeMonth,
+  evalTimeDay,
+  evalTimeWeekday,
+  evalTimeHour,
+  evalTimeMinute,
+  evalTimeSecond,
+  evalTimeAdd,
+  evalTimeSubtract,
+  evalTimeDiff,
+  evalTimeStartOf,
+  evalTimeEndOf,
+  evalTimeIsBefore,
+  evalTimeIsAfter,
+  evalTimeIsBetween,
+  evalTimeIsSame,
+  evalTimeIsPast,
+  evalTimeIsFuture,
+  evalTimeIsToday,
+  evalTimeRelative,
+  evalTimeDuration,
+} from './time.js';
+
+// Format operators
+export {
+  evalFormatNumber,
+  evalFormatCurrency,
+  evalFormatPercent,
+  evalFormatBytes,
+  evalFormatOrdinal,
+  evalFormatPlural,
+  evalFormatList,
+  evalFormatPhone,
+  evalFormatCreditCard,
+} from './format.js';
+
+// Async operators
+export {
+  evalAsyncDelay,
+  evalAsyncTimeout,
+  evalAsyncDebounce,
+  evalAsyncThrottle,
+  evalAsyncRetry,
+  evalAsyncRace,
+  evalAsyncAll,
+  evalAsyncSequence,
+  clearDebounceTimers,
+  clearThrottleTimestamps,
+} from './async.js';