@adviser/cement 0.5.0 → 0.5.2

package/src/logger-impl.ts

@@ -1,18 +1,13 @@
 // import { v4 } from "uuid";
-// import YAML from "yaml";
+import YAML from "yaml";
 import {
   AsError,
-  FnSerialized,
-  LogSerializable,
-  Level,
   Logger,
   logValue,
-  Serialized,
   WithLogger,
   // sanitizeSerialize,
   Sized,
   Lengthed,
-  LogValue,
   LevelHandler,
   LogFormatter,
   LogValueArg,
@@ -26,7 +21,7 @@ import { TxtEnDecoder, TxtEnDecoderSingleton } from "./txt-en-decoder.js";
 import { LevelHandlerSingleton } from "./log-level-impl.js";
 import { BasicSysAbstractionFactory } from "./base-sys-abstraction.js";
 import { LogWriterStream } from "./log-writer-impl.js";
-import type YAML from "yaml";
+import { LogValue, LogSerializable, Level, FnSerialized, Serialized } from "./types.js";
 
 function getLen(value: unknown, lvs: LogValueState): LogValue {
   if (Array.isArray(value)) {
@@ -76,22 +71,16 @@ export class JSONFormatter implements LogFormatter {
     return this._txtEnDe.encode(ret + "\n");
   }
 }
+
 export class YAMLFormatter implements LogFormatter {
   private readonly _txtEnDe: TxtEnDecoder;
   private readonly _space?: number;
-  private readonly _yaml: typeof YAML;
-
-  static create(txtEnde: TxtEnDecoder, space?: number): Promise<YAMLFormatter> {
-    return import("yaml").then((yaml) => new YAMLFormatter(txtEnde, space, yaml));
-  }
-
-  private constructor(txtEnde: TxtEnDecoder, space: number | undefined, yaml: typeof YAML) {
+  constructor(txtEnde: TxtEnDecoder, space?: number) {
     this._txtEnDe = txtEnde;
     this._space = space;
-    this._yaml = yaml;
   }
   format(attr: LogSerializable): Uint8Array {
-    return this._txtEnDe.encode("---\n" + this._yaml.stringify(attr, null, this._space) + "\n");
+    return this._txtEnDe.encode("---\n" + YAML.stringify(attr, null, this._space) + "\n");
   }
 }
 

package/src/logger.ts

@@ -7,35 +7,7 @@ import { TxtEnDecoder, TxtEnDecoderSingleton } from "./txt-en-decoder.js";
 import { CoerceURI } from "./uri.js";
 import { isJSON } from "./is-json.js";
 import { ReadonlyURL } from "./mutable-url.js";
-
-export const Level = {
-  WARN: "warn",
-  DEBUG: "debug",
-  INFO: "info",
-  ERROR: "error",
-};
-
-export type Level = (typeof Level)[keyof typeof Level];
-
-export type Serialized = string | number | boolean;
-export type FnSerialized = () => Serialized | Serialized[];
-
-export class LogValue {
-  constructor(readonly fn: FnSerialized) {}
-  value(): Serialized | Serialized[] {
-    try {
-      // console.log("LogValue.value", this.fn.toString());
-      return this.fn();
-    } catch (e) {
-      return `LogValue:${(e as Error).message}`;
-    }
-  }
-  toJSON(): Serialized | Serialized[] {
-    return this.value();
-  }
-}
-
-export type LogSerializable = Record<string, LogValue | Promise<LogValue>>;
+import { FnSerialized, Level, LogSerializable, LogValue, Serialized } from "./types.js";
 
 // export function sanitizeSerialize(lineEnd?: string): (key: unknown, val: unknown) => unknown {
 //   const cache = new Set();
@@ -149,8 +121,15 @@ function logValueInternal(val: LogValueArg, ctx: LogValueStateInternal): LogValu
         return new LogValue(() => "...");
       }
       ctx.state?.add(val);
-      if (typeof val.toJSON === "function") {
-        return new LogValue(() => val.toJSON());
+      try {
+        if (typeof val.toJSON === "function") {
+          return new LogValue(() => val.toJSON());
+        }
+      } catch (e) {
+        /* chrome is a strange beast
+           Failed to read a named property 'toJSON' from 'Window':
+           Blocked a frame with origin "http://localhost:3001" from accessing a cross-origin frame.
+         */
       }
 
       const res: Record<string, LogValue> = {};

package/src/lru-map-set.ts

@@ -11,6 +11,25 @@ interface MutableLRUParam<T, K> {
 
 export type LRUParam<T = string, K = string> = Readonly<MutableLRUParam<T, K>>;
 
+/**
+ * A Set implementation with Least Recently Used (LRU) eviction policy.
+ *
+ * LRUSet maintains a set of values with automatic eviction of least recently
+ * accessed items when capacity limits are reached. Items are moved to the end
+ * of the access order when accessed.
+ *
+ * @template T - The type of values in the set
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUSet<string>({ maxEntries: 3 });
+ * cache.add('a');
+ * cache.add('b');
+ * cache.add('c');
+ * cache.add('d'); // 'a' is evicted
+ * console.log(cache.has('a')); // false
+ * ```
+ */
 export class LRUSet<T> {
   readonly #lruMap: LRUMap<T, T>;
 
@@ -51,6 +70,8 @@ export class LRUSet<T> {
   }
 }
 
+export type LRUWithIdx<T> = T & { readonly idx: number };
+
 export interface LRUCtx<T, K> {
   readonly update: boolean;
   readonly ref: LRUMap<K, T>;
@@ -84,6 +105,33 @@ function defaultRefresh<V, K>(param: LRUParam<V, K>, map: LRUMap<K, V>): void {
   }
 }
 
+/**
+ * A Map implementation with Least Recently Used (LRU) eviction policy.
+ *
+ * LRUMap maintains key-value pairs with automatic eviction of least recently
+ * accessed items when capacity limits are reached. Provides configurable
+ * eviction and refresh strategies, event callbacks, and access statistics.
+ *
+ * @template K - The type of keys in the map
+ * @template V - The type of values in the map
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUMap<string, number>({ maxEntries: 100 });
+ *
+ * // Add items
+ * cache.set('key1', 42);
+ * cache.set('key2', 100);
+ *
+ * // Get items (updates access order)
+ * const value = cache.get('key1');
+ *
+ * // Listen for evictions
+ * const unregister = cache.onDelete((key, value) => {
+ *   console.log(`Evicted: ${key} = ${value}`);
+ * });
+ * ```
+ */
 export class LRUMap<K, V> {
   private _map: Map<K, LRUItem<V>> = new Map<K, LRUItem<V>>();
   private param: MutableLRUParam<V, K>;
@@ -124,7 +172,6 @@ export class LRUMap<K, V> {
     if (!this._map.has(key)) {
       throw new Error(`key not found in cache: ${key as unknown as string}`);
     }
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
     const value = this._map.get(key) as LRUItem<V>;
     this._map.delete(key);
     this._map.set(key, value);
@@ -207,7 +254,7 @@ export class LRUMap<K, V> {
       // this.cache.delete(key) or
       const k = this._map.keys().next();
       if (!k.done) {
-        this._map.delete(k.value as K);
+        this._map.delete(k.value);
       }
     }
     this._map.set(key, item);
@@ -226,7 +273,6 @@ export class LRUMap<K, V> {
 
   delete(key: K): void {
     if (this._map.has(key)) {
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
       const item = this._map.get(key) as LRUItem<V>;
       this._onDeleteFns.forEach((fn) => fn(key, item?.value, this.buildItemCtx(item, true)));
       this._map.delete(key);
@@ -243,9 +289,11 @@ export class LRUMap<K, V> {
     this._map.clear();
   }
 
-  forEach(fn: (value: V, key: K, ctx: LRUCtx<V, K>) => void): void {
+  forEach(fn: (value: V, key: K, ctx: LRUWithIdx<LRUCtx<V, K>>) => void): void {
+    let idx = 0;
     this._map.forEach((v, k) => {
-      fn(v.value, k, this.buildItemCtx(v, false));
+      // not really efficient but ok for now
+      fn(v.value, k, { ...this.buildItemCtx(v, false), idx: idx++ });
     });
   }
 

package/src/mutable-url.ts

@@ -1,5 +1,5 @@
 import { exception2Result, Result } from "./result.js";
-import { hasHostPartProtocols } from "./uri.js";
+import { hasHostPartProtocols } from "./types.js";
 
 // due to that the System URL class is has a strange behavior
 // on different platforms, we need to implement our own URL class

package/src/node-env/index.ts

@@ -0,0 +1,2 @@
+export * from "./node-env-actions.js";
+export * from "./node-basic-sys-abstraction.js";

package/src/node-env/node-basic-sys-abstraction.ts

@@ -0,0 +1,66 @@
+import {
+  BaseBasicRuntimeSysAbstractionParams,
+  BaseBasicSysAbstraction,
+  WrapperBasicSysAbstraction,
+} from "../base-sys-abstraction.js";
+import { BasicRuntimeService, BasicSysAbstraction } from "../sys-abstraction.js";
+import { Env, envFactory, EnvFactory } from "../sys-env.js";
+import { TxtEnDecoder, TxtEnDecoderSingleton } from "../txt-en-decoder.js";
+
+export class NodeRuntimeService implements BasicRuntimeService {
+  readonly _txtEnDe: TxtEnDecoder;
+  readonly _envFactory: EnvFactory;
+  readonly _gthis: {
+    process: {
+      argv: string[];
+      stdout: {
+        write(chunk: Uint8Array): void;
+      };
+      stderr: {
+        write(chunk: Uint8Array): void;
+      };
+    };
+  };
+  constructor(ende: TxtEnDecoder, envFactory: EnvFactory) {
+    this._txtEnDe = ende;
+    this._envFactory = envFactory;
+    this._gthis = globalThis as unknown as NodeRuntimeService["_gthis"];
+  }
+  Env(): Env {
+    return this._envFactory();
+  }
+
+  Args(): string[] {
+    return this._gthis.process.argv;
+  }
+
+  Stdout(): WritableStream<Uint8Array> {
+    return new WritableStream({
+      write: (chunk: Uint8Array): void => {
+        this._gthis.process.stdout.write(chunk);
+      },
+    });
+  }
+  Stderr(): WritableStream<Uint8Array> {
+    return new WritableStream<Uint8Array>({
+      write: (chunk: Uint8Array): void => {
+        this._gthis.process.stderr.write(chunk);
+      },
+    });
+  }
+}
+
+let baseSysAbstraction: BaseBasicSysAbstraction | undefined = undefined;
+
+export function NodeBasicSysAbstraction(param: Partial<BaseBasicRuntimeSysAbstractionParams> = {}): BasicSysAbstraction {
+  const ende = param.TxtEnDecoder ?? TxtEnDecoderSingleton();
+  baseSysAbstraction =
+    baseSysAbstraction ??
+    new BaseBasicSysAbstraction({
+      TxtEnDecoder: ende,
+    });
+  return new WrapperBasicSysAbstraction(baseSysAbstraction, {
+    basicRuntimeService: new NodeRuntimeService(ende, envFactory),
+    ...param,
+  });
+}

package/src/node-env/node-env-actions.ts

@@ -0,0 +1,46 @@
+import { runtimeFn } from "../runtime.js";
+import { Env, EnvActions, EnvFactoryOpts } from "../sys-env.js";
+
+let once: NodeEnvActions | undefined = undefined;
+
+export class NodeEnvActions implements EnvActions {
+  readonly #node = globalThis as unknown as { process: { env: Record<string, string> } };
+  readonly _env: Record<string, string>;
+
+  static new(opts: Partial<EnvFactoryOpts>): EnvActions {
+    once = once ?? new NodeEnvActions(opts);
+    return once;
+  }
+
+  readonly opts: Partial<EnvFactoryOpts>;
+  private constructor(opts: Partial<EnvFactoryOpts>) {
+    this.opts = opts;
+    this._env = this.active() ? this.#node.process.env : {};
+  }
+
+  register(env: Env): Env {
+    for (const key of env.keys()) {
+      this._env[key] = env.get(key) || "";
+    }
+    return env;
+  }
+
+  active(): boolean {
+    return runtimeFn().isNodeIsh;
+  }
+  keys(): string[] {
+    return Object.keys(this._env);
+  }
+  get(key: string): string | undefined {
+    return this._env[key];
+  }
+  set(key: string, value?: string): void {
+    if (value) {
+      this._env[key] = value;
+    }
+  }
+  delete(key: string): void {
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    delete this._env[key];
+  }
+}

package/src/node-fs/mock-file-service.ts

@@ -0,0 +1,45 @@
+import type { NamedWritableStream } from "@adviser/cement";
+import { NodeFileService } from "./node-file-service.js";
+
+export interface FileCollector {
+  readonly name: string;
+  content: string;
+}
+
+export class MockFileService extends NodeFileService {
+  readonly files = {} as Record<string, FileCollector>;
+
+  // override abs(fname: string): string {
+  //   return this.join("/mock/", fname);
+  // }
+
+  override create(fname: string): Promise<NamedWritableStream> {
+    let oName = fname;
+    if (!this.isAbsolute(fname)) {
+      oName = this.abs(fname);
+    }
+
+    const fc = {
+      name: oName,
+      content: "",
+    };
+    this.files[oName] = fc;
+    this.files[fname] = fc;
+    const decoder = this.defTxtEnde;
+
+    return Promise.resolve({
+      name: oName,
+      stream: new WritableStream<Uint8Array>({
+        write(chunk): void {
+          fc.content = fc.content + decoder.decode(chunk);
+        },
+        close(): void {
+          // do nothing
+        },
+        abort(): void {
+          throw new Error("not implemented");
+        },
+      }),
+    });
+  }
+}

package/src/node-fs/node-file-service.ts

@@ -0,0 +1,92 @@
+import path from "node:path";
+import fs from "node:fs";
+import process from "node:process";
+import type { FileService, NamedWritableStream, TxtEnDecoder } from "@adviser/cement";
+
+export class NodeFileService implements FileService {
+  readonly baseDir: string;
+  readonly defTxtEnde: TxtEnDecoder;
+  constructor(defTxtEncode: TxtEnDecoder, baseDir: string = process.cwd()) {
+    this.baseDir = this.abs(baseDir);
+    this.defTxtEnde = defTxtEncode;
+  }
+
+  // nodeImport(fname: string): string {
+  //   // console.log('nodeImport:'+ fname);
+  //   if (path.isAbsolute(fname)) {
+  //     return fname;
+  //   } else {
+  //     return "./" + path.normalize(fname);
+  //   }
+  // }
+
+  readFileString(fname: string): Promise<string> {
+    return fs.promises.readFile(fname, { encoding: "utf-8" });
+  }
+
+  dirname(fname: string): string {
+    return path.dirname(fname);
+  }
+  basename(fname: string): string {
+    return path.basename(fname);
+  }
+
+  join(...paths: string[]): string {
+    return path.join(...paths);
+  }
+
+  relative(from: string, to?: string): string {
+    if (to === undefined) {
+      to = from;
+      from = process.cwd();
+    }
+    const ret = path.relative(from, to);
+    // console.log('relative:'+ from + " -> " + to +   "= " + ret);
+    return ret;
+  }
+
+  abs(fname: string): string {
+    if (path.isAbsolute(fname)) {
+      return fname;
+    } else {
+      const cwd = process.cwd();
+      return path.resolve(cwd, fname);
+    }
+  }
+
+  isAbsolute(fname: string): boolean {
+    return path.isAbsolute(fname);
+  }
+
+  async writeFileString(fname: string, content: string, ende: TxtEnDecoder = this.defTxtEnde): Promise<void> {
+    const o = await this.create(fname);
+    const wr = o.stream.getWriter();
+    await wr.write(ende.encode(content));
+    await wr.close();
+  }
+
+  async create(fname: string): Promise<NamedWritableStream> {
+    let oName = fname;
+    if (!path.isAbsolute(fname)) {
+      oName = this.abs(fname);
+    }
+
+    const base = path.dirname(oName);
+    await fs.promises.mkdir(base, { recursive: true });
+    const out = fs.createWriteStream(oName);
+    return {
+      name: oName,
+      stream: new WritableStream<Uint8Array>({
+        write(chunk): void {
+          out.write(chunk);
+        },
+        close(): void {
+          out.close();
+        },
+        abort(): void {
+          throw new Error("not implemented");
+        },
+      }),
+    };
+  }
+}

package/src/node-fs/node-sys-abstraction.ts

@@ -0,0 +1,116 @@
+import type {
+  RuntimeSysAbstraction,
+  SystemService,
+  VoidFunc,
+  BaseSysAbstraction,
+  ExitHandler,
+  ExitService,
+  WithCementWrapperSysAbstractionParams,
+} from "@adviser/cement";
+import { NodeFileService } from "./node-file-service.js";
+import process from "node:process";
+
+export class NodeExitServiceImpl implements ExitService {
+  constructor() {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    process.on("unhandledRejection", (reason: string, p: Promise<unknown>) => {
+      this.exit(19);
+    });
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    process.on("uncaughtException", (error: Error) => {
+      this.exit(18);
+    });
+    process.on("close", () => {
+      this.exit(0);
+    });
+    process.on("exit", () => {
+      this.exit(0);
+    });
+    process.on("SIGQUIT", () => {
+      this.exit(3);
+    });
+    process.on("SIGINT", () => {
+      this.exit(2);
+    });
+    process.on("SIGTERM", () => {
+      this.exit(9);
+    });
+  }
+  _exitHandlers: ExitHandler[] = [];
+  injectExitHandlers(hdls: ExitHandler[]): void {
+    // console.log("ExitService: injecting exit handlers", hdls)
+    this._exitHandlers = hdls;
+  }
+  invoked = false;
+  readonly _handleExit = async (): Promise<void> => {
+    if (this.invoked) {
+      // console.error("ExitService: already invoked");
+      return;
+    }
+    this.invoked = true;
+    for (const h of this._exitHandlers) {
+      try {
+        // console.log(`ExitService: calling handler ${h.id}`)
+        const ret = h.hdl();
+        // console.log(`ExitService: called handler ${h.id}`, ret)
+        if (typeof (ret as Promise<void>).then === "function") {
+          await ret;
+        }
+      } finally {
+        // ignore
+      }
+    }
+  };
+
+  exit(code: number): void {
+    // console.log("ExitService: exit called", code)
+    this._handleExit()
+      .then(() => {
+        process.exit(code);
+      })
+      .catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error("ExitService: failed to handle exit", err);
+        process.exit(code);
+      });
+  }
+}
+
+export class NodeSystemService implements SystemService {
+  static readonly _exitHandlers: ExitHandler[] = [];
+  readonly _exitService: ExitService = new NodeExitServiceImpl();
+  constructor() {
+    this._exitService.injectExitHandlers(NodeSystemService._exitHandlers);
+  }
+
+  OnExit(hdl: VoidFunc): VoidFunc {
+    const id = crypto.randomUUID();
+    NodeSystemService._exitHandlers.push({ hdl, id });
+    return () => {
+      const idx = NodeSystemService._exitHandlers.findIndex((h) => h.id === id);
+      if (idx >= 0) {
+        NodeSystemService._exitHandlers.splice(idx, 1);
+      }
+    };
+  }
+
+  Exit(code: number): void {
+    this._exitService.exit(code);
+  }
+}
+
+let baseSysAbstraction: BaseSysAbstraction | undefined = undefined;
+export function NodeSysAbstraction(param: WithCementWrapperSysAbstractionParams): RuntimeSysAbstraction {
+  const ende = param?.TxtEnDecoder || param.cement.TxtEnDecoderSingleton();
+  baseSysAbstraction =
+    baseSysAbstraction ??
+    new param.cement.BaseSysAbstraction({
+      TxtEnDecoder: ende,
+      FileSystem: new NodeFileService(ende),
+      SystemService: new NodeSystemService(),
+    });
+  return new param.cement.WrapperRuntimeSysAbstraction(baseSysAbstraction, {
+    basicRuntimeService: param.cement.NodeBasicSysAbstraction(param),
+    ...param,
+  });
+}