@adviser/cement 0.5.0 → 0.5.1

package/src/result.ts

@@ -1,8 +1,35 @@
 import { isPromise } from "./is-promise.js";
 
+/**
+ * Result type for representing success (Ok) or failure (Err) values.
+ *
+ * Result is a type-safe way to handle operations that can fail, similar to Rust's
+ * Result type. It forces explicit handling of both success and error cases without
+ * throwing exceptions.
+ *
+ * @template T - The type of the success value
+ * @template E - The type of the error (default: Error)
+ *
+ * @example
+ * ```typescript
+ * function divide(a: number, b: number): Result<number> {
+ *   if (b === 0) {
+ *     return Result.Err('Division by zero');
+ *   }
+ *   return Result.Ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (result.isOk()) {
+ *   console.log('Result:', result.unwrap());
+ * } else {
+ *   console.error('Error:', result.unwrap_err());
+ * }
+ * ```
+ */
 export abstract class Result<T, E = Error> {
-  static Ok<T = void>(...args: T[]): Result<T, Error> {
-    return args.length >= 1 ? new ResultOK<T>(args[0]) : new ResultOK<T>(undefined as unknown as T);
+  static Ok<T = void, E = Error>(...args: T[]): Result<T, E> {
+    return args.length >= 1 ? new ResultOK<T, E>(args[0]) : new ResultOK<T, E>(undefined as unknown as T);
   }
   static Err<T, E extends Error = Error>(t: E | string | Result<unknown, E>): Result<T, E> {
     if (typeof t === "string") {
@@ -50,7 +77,7 @@ export abstract class Result<T, E = Error> {
   abstract unwrap_err(): E;
 }
 
-export class ResultOK<T> extends Result<T, Error> {
+export class ResultOK<T, E = unknown> extends Result<T, E> {
   private _t: T;
   constructor(t: T) {
     super();
@@ -62,7 +89,7 @@ export class ResultOK<T> extends Result<T, Error> {
   is_err(): boolean {
     return false;
   }
-  unwrap_err(): Error {
+  unwrap_err(): E {
     throw new Error("Result is Ok");
   }
   unwrap(): T {
@@ -95,6 +122,29 @@ export type WithoutResult<T> = T extends Result<infer U> ? U : T;
 // type WithoutPromise<T> = T extends Promise<infer U> ? U : T;
 type WithResult<T> = T extends Promise<infer U> ? Promise<Result<U>> : Result<T>;
 
+/**
+ * Wraps a function to convert thrown exceptions into Result.Err values.
+ *
+ * Executes the provided function and returns Result.Ok on success or Result.Err
+ * on thrown exceptions. Supports both synchronous and asynchronous functions.
+ *
+ * @template FN - Function type that returns T or Promise<T>
+ * @template T - The return type of the function
+ * @param fn - Function to execute with exception handling
+ * @returns Result<T> for sync functions, Promise<Result<T>> for async functions
+ *
+ * @example
+ * ```typescript
+ * const result = exception2Result(() => {
+ *   return JSON.parse('invalid json');
+ * });
+ * // result is Result.Err with parse error
+ *
+ * const asyncResult = await exception2Result(async () => {
+ *   return await fetch('/api/data');
+ * });
+ * ```
+ */
 export function exception2Result<FN extends () => Promise<T> | T, T>(fn: FN): WithResult<ReturnType<FN>> {
   try {
     const res = fn();

package/src/runtime.ts

@@ -1,11 +1,51 @@
+/**
+ * Runtime environment detection result.
+ *
+ * Provides boolean flags indicating which JavaScript runtime environment
+ * the code is currently executing in. Only one flag should be true at a time,
+ * allowing for runtime-specific behavior and feature detection.
+ *
+ * @example
+ * ```typescript
+ * const runtime = runtimeFn();
+ * if (runtime.isNodeIsh) {
+ *   console.log('Running in Node.js or Bun');
+ * } else if (runtime.isBrowser) {
+ *   console.log('Running in a browser');
+ * }
+ * ```
+ */
 export interface Runtime {
+  /** True if running in Node.js or Node-compatible runtime (e.g., Bun) */
   isNodeIsh: boolean;
+  /** True if running in a web browser */
   isBrowser: boolean;
+  /** True if running in Deno */
   isDeno: boolean;
+  /** True if running in React Native */
   isReactNative: boolean;
+  /** True if running in Cloudflare Workers */
   isCFWorker: boolean;
 }
 
+/**
+ * Checks if a nested property path exists on an object.
+ *
+ * Recursively traverses dot-separated property paths to determine if they exist
+ * and are truthy. Used internally for runtime environment detection by checking
+ * for environment-specific global objects.
+ *
+ * @param value - Dot-separated property path to check (e.g., "process.versions.node")
+ * @param ref - Object to check properties on (defaults to globalThis)
+ * @returns True if the full path exists and all values are truthy
+ *
+ * @example
+ * ```typescript
+ * isSet("process.versions.node"); // true in Node.js
+ * isSet("Deno"); // true in Deno
+ * isSet("navigator.userAgent"); // true in browsers
+ * ```
+ */
 function isSet(value: string, ref: Record<string, unknown> = globalThis): boolean {
   const [head, ...tail] = value.split(".");
   if (["object", "function"].includes(typeof ref) && ref && ["object", "function"].includes(typeof ref[head]) && ref[head]) {
@@ -17,8 +57,41 @@ function isSet(value: string, ref: Record<string, unknown> = globalThis): boolea
   return false;
 }
 
-// caches.default or WebSocketPair
-
+/**
+ * Detects the current JavaScript runtime environment.
+ *
+ * Performs feature detection to identify which runtime environment the code
+ * is executing in. Checks for environment-specific global objects and APIs
+ * in priority order:
+ * 1. Cloudflare Workers (caches.default + WebSocketPair)
+ * 2. React Native (navigator.product === "ReactNative")
+ * 3. Deno (global Deno object)
+ * 4. Node.js (process.versions.node)
+ * 5. Browser (none of the above)
+ *
+ * The detection is mutually exclusive - only one environment flag will be true.
+ *
+ * @returns Runtime object with boolean flags for each environment
+ *
+ * @example
+ * ```typescript
+ * const runtime = runtimeFn();
+ *
+ * if (runtime.isNodeIsh) {
+ *   // Use Node.js APIs
+ *   const fs = require('fs');
+ * } else if (runtime.isBrowser) {
+ *   // Use browser APIs
+ *   console.log(window.location.href);
+ * } else if (runtime.isDeno) {
+ *   // Use Deno APIs
+ *   const file = await Deno.readTextFile('./config.json');
+ * } else if (runtime.isCFWorker) {
+ *   // Use Cloudflare Workers APIs
+ *   const cache = caches.default;
+ * }
+ * ```
+ */
 export function runtimeFn(): Runtime {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const gt: any = globalThis;

package/src/sys-env.ts

@@ -1,11 +1,13 @@
-import { DenoEnvActions } from "./deno/deno-env-actions.js";
-import { NodeEnvActions } from "./node/node-env-actions.js";
-import { BrowserEnvActions } from "./web/web-env-actions.js";
-import { CFEnvActions } from "./cf/cf-env-actions.js";
+import { DenoEnvActions } from "./deno-env/index.js";
+import { NodeEnvActions } from "./node-env/index.js";
+import { BrowserEnvActions } from "./web-env/index.js";
+import { CFEnvActions } from "./cf-env/index.js";
 import { KeyedResolvOnce } from "./resolve-once.js";
 import { Result } from "./result.js";
+import { wrapImportMetaEnv, ImportMetaEnv } from "@adviser/cement/import-meta-env";
 import { getParamsResult, KeysParam } from "./utils/get-params-result.js";
-import { wrapImportMetaEnv, testInjectImportMetaEnv } from "@adviser/cement/import-meta-env";
+import { WithCement } from "./types.js";
+import { addCement } from "./add-cement-do-not-export.js";
 
 export type EnvTuple = ([string, string] | [string, string][] | Record<string, string> | Iterator<[string, string]>)[];
 
@@ -40,15 +42,35 @@ export interface Env extends EnvMap {
   sets(...keys: EnvTuple): void;
 }
 
-export type EnvFactoryFn = (opts: Partial<EnvFactoryOpts>) => EnvActions;
+export type EnvFactoryFn = (opts: WithCement<Partial<EnvFactoryOpts>>) => EnvActions;
 
 const envActions: { id: string; fn: EnvFactoryFn }[] = [
-  { id: "cf", fn: (opts: Partial<EnvFactoryOpts>): EnvActions => CFEnvActions.new(opts) },
-  { id: "node", fn: (opts: Partial<EnvFactoryOpts>): EnvActions => NodeEnvActions.new(opts) },
-  { id: "deno", fn: (opts: Partial<EnvFactoryOpts>): EnvActions => DenoEnvActions.new(opts) },
-  { id: "browser", fn: (opts: Partial<EnvFactoryOpts>): EnvActions => BrowserEnvActions.new(opts) },
+  { id: "cf", fn: (opts: WithCement<Partial<EnvFactoryOpts>>): EnvActions => CFEnvActions.new(opts) },
+  { id: "node", fn: (opts: WithCement<Partial<EnvFactoryOpts>>): EnvActions => NodeEnvActions.new(opts) },
+  { id: "deno", fn: (opts: WithCement<Partial<EnvFactoryOpts>>): EnvActions => DenoEnvActions.new(opts) },
+  { id: "browser", fn: (opts: WithCement<Partial<EnvFactoryOpts>>): EnvActions => BrowserEnvActions.new(opts) },
 ];
 
+/**
+ * Registers a custom environment action factory.
+ *
+ * Allows registration of platform-specific environment implementations.
+ * The factory is added to the beginning of the search list and will be
+ * tried first when creating new Env instances.
+ *
+ * @param fn - Factory function that creates EnvActions for a platform
+ * @returns Unregister function to remove the factory
+ *
+ * @example
+ * ```typescript
+ * const unregister = registerEnvAction((opts) => {
+ *   return new CustomEnvActions(opts);
+ * });
+ *
+ * // Later, remove the factory
+ * unregister();
+ * ```
+ */
 export function registerEnvAction(fn: EnvFactoryFn): () => void {
   const id = `id-${Math.random()}`;
   envActions.unshift({ id, fn });
@@ -63,20 +85,65 @@ export function registerEnvAction(fn: EnvFactoryFn): () => void {
 }
 
 const _envFactories = new KeyedResolvOnce<Env>();
+
+/**
+ * Creates a platform-appropriate environment variable interface.
+ *
+ * Automatically detects the runtime environment (Node.js, Deno, browser,
+ * Cloudflare Workers) and returns an Env instance with platform-specific
+ * implementations. Supports preset values, change notifications, and
+ * type-safe multi-key retrieval.
+ *
+ * @param opts - Optional configuration:
+ *   - symbol: Key for browser environment storage (default: "CP_ENV")
+ *   - presetEnv: Map of preset environment variables
+ *   - testPatchImportMetaEnv: Test values to patch into import.meta.env
+ *   - id: Identifier for caching/reinitialization
+ *
+ * @returns Env instance for the detected platform
+ * @throws Error if no compatible environment is detected
+ *
+ * @example
+ * ```typescript
+ * const env = envFactory();
+ *
+ * // Get single value
+ * const apiKey = env.get('API_KEY');
+ *
+ * // Get multiple values with Result
+ * const config = env.gets('DB_HOST', 'DB_PORT', 'DB_NAME');
+ * if (config.isOk()) {
+ *   const { DB_HOST, DB_PORT, DB_NAME } = config.unwrap();
+ * }
+ *
+ * // Listen for changes
+ * env.onSet((key, value) => {
+ *   console.log(`${key} changed to ${value}`);
+ * }, 'API_KEY'); // Optional: filter by specific keys
+ * ```
+ */
+export type EnvFactory = (opts?: Partial<EnvFactoryOpts>) => Env;
 export function envFactory(opts: Partial<EnvFactoryOpts> = {}): Env {
-  const found = envActions.find((fi) => fi.fn(opts).active());
+  const withCement = addCement(opts);
+  const found = envActions.find((fi) => fi.fn(withCement).active());
   if (!found) {
     throw new Error("SysContainer:envFactory: no env available");
   }
-
-  testInjectImportMetaEnv(opts.testPatchImportMetaEnv);
-
-  return _envFactories.get(opts.id ?? found.id).once(() => {
-    const action = wrapImportMetaEnv(found.fn(opts));
-    const ret = new EnvImpl(action, opts);
+  const res = _envFactories.get(opts.id ?? found.id).once(() => {
+    const action = wrapImportMetaEnv(found.fn(withCement));
+    const ret = new EnvImpl(action, withCement);
     action.register(ret);
     return ret;
   });
+  if (opts.testPatchImportMetaEnv && isImportMetaEnv(res._map) && res._map.importMetaEnv) {
+    // do not override possible readonly meta.env
+    Object.assign(res._map.importMetaEnv, opts.testPatchImportMetaEnv);
+  }
+  return res;
+}
+
+function isImportMetaEnv(obj: EnvMap): obj is ImportMetaEnv {
+  return !!(obj as ImportMetaEnv).importMetaEnv;
 }
 
 function isIterable(obj: unknown): obj is Iterable<[string, string]> {
@@ -89,7 +156,7 @@ function isIterable(obj: unknown): obj is Iterable<[string, string]> {
 
 export class EnvImpl implements Env {
   readonly _map: EnvMap;
-  constructor(map: EnvMap, opts: Partial<EnvFactoryOpts> = {}) {
+  constructor(map: EnvMap, opts: Partial<EnvFactoryOpts>) {
     this._map = map;
     this._updatePresets(opts.presetEnv);
   }

package/src/test/log-write-stream.ts

@@ -1,6 +1,4 @@
-import { FanoutWriteStream } from "../utils/fanout-write-stream.js";
-import { Future } from "../future.js";
-import { TxtEnDecoder, TxtEnDecoderSingleton } from "../txt-en-decoder.js";
+import { FanoutWriteStream, Future, type TxtEnDecoder, TxtEnDecoderSingleton } from "@adviser/cement";
 
 export class LogWriteStream implements WritableStreamDefaultWriter<Uint8Array> {
   private readonly _bufferArr: Uint8Array[];

package/src/test/mock-logger.ts

@@ -1,8 +1,5 @@
-import { LevelHandlerImpl } from "../log-level-impl.js";
-import { Logger } from "../logger.js";
-import { LoggerImpl } from "../logger-impl.js";
+import { LevelHandlerImpl, type Logger, LoggerImpl, type BasicSysAbstraction } from "@adviser/cement";
 import { LogCollector } from "./log-write-stream.js";
-import { BasicSysAbstraction } from "../sys-abstraction.js";
 
 export interface MockLoggerReturn {
   readonly logger: Logger;