@adviser/cement 0.5.0 → 0.5.1

package/src/cli/utils.ts

@@ -0,0 +1,70 @@
+import * as ts from "typescript";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import * as process from "node:process";
+import { $ } from "zx";
+
+// Custom compiler host
+export function createCompilerHost(options: ts.CompilerOptions, version: string): ts.CompilerHost {
+  const host = ts.createCompilerHost(options);
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const myGetSourceFile = host.getSourceFile;
+
+  host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile): ts.SourceFile => {
+    const sourceFile = myGetSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    if (!sourceFile) {
+      throw new Error("getSourceFile is not defined");
+    }
+
+    // Patch version.ts during compilation
+    if (fileName.endsWith("version.ts") && sourceFile) {
+      const newText = `export const VERSION: string = "${version}";`;
+      return ts.createSourceFile(fileName, newText, languageVersion);
+    }
+
+    return sourceFile;
+  };
+  return host;
+}
+
+export function readTSConfig(configPath = "./tsconfig.json"): ts.CompilerOptions {
+  // Read the config file
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+
+  if (configFile.error) {
+    throw new Error(`Error reading tsconfig: ${configFile.error.messageText as string}`);
+  }
+
+  // Parse and resolve the config
+  const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath), undefined, configPath);
+
+  if (parsedConfig.errors.length > 0) {
+    const errors = parsedConfig.errors.map((err) => err.messageText as string).join("\n");
+    throw new Error(`Error parsing tsconfig: ${errors}`);
+  }
+
+  return parsedConfig.options; // This is CompilerOptions
+}
+
+export function versionFromPackageJson(): string {
+  const packageJson = JSON.parse(fs.readFileSync("package.json").toString()) as { version: string };
+  return packageJson.version;
+}
+
+export function getVersion(iversion?: string): string {
+  const ghref = iversion || process.env.GITHUB_REF || versionFromPackageJson() || "a/v0.0.0-smoke";
+  let lastPart = ghref.split("/").slice(-1)[0];
+  if (iversion) {
+    return iversion.replace(/^[vdsp]/, "");
+  }
+  const short = $.sync`git rev-parse --short HEAD`.stdout.trim();
+  if (process.env.GITHUB_REF) {
+    lastPart = lastPart.replace(/^[vdsp]/, "");
+    if (lastPart.match(/^\d+\.\d+\.\d+/)) {
+      return lastPart;
+    }
+    return `0.0.0-dev-ci-${short}`;
+  }
+  return `0.0.0-dev-local-${Date.now()}`;
+}

package/src/coerce-binary.ts

@@ -2,6 +2,32 @@ import { TxtEnDecoderSingleton } from "./txt-en-decoder.js";
 
 export type CoerceBinaryInput = string | ArrayBufferLike | ArrayBufferView | Uint8Array; // | SharedArrayBuffer
 
+/**
+ * Type guard to check if a value is an ArrayBuffer.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an ArrayBuffer
+ */
+export function isArrayBuffer(value: unknown): value is ArrayBuffer {
+  return value instanceof ArrayBuffer || Object.prototype.toString.call(value) === "[object ArrayBuffer]";
+}
+
+/**
+ * Type guard to check if a value is a Uint8Array.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Uint8Array
+ */
+export function isUint8Array(value: unknown): value is Uint8Array {
+  return value instanceof Uint8Array || Object.prototype.toString.call(value) === "[object Uint8Array]";
+}
+
+/**
+ * Converts various binary input types (including Blob) to Uint8Array asynchronously.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, Uint8Array, or Blob to convert
+ * @returns Promise resolving to Uint8Array
+ */
 export async function top_uint8(input: CoerceBinaryInput | Blob): Promise<Uint8Array> {
   if (input instanceof Blob) {
     return new Uint8Array(await input.arrayBuffer());
@@ -9,21 +35,37 @@ export async function top_uint8(input: CoerceBinaryInput | Blob): Promise<Uint8A
   return to_uint8(input);
 }
 
+/**
+ * Converts various binary input types to Uint8Array synchronously.
+ *
+ * Handles strings (encoding with TextEncoder), ArrayBuffers, and ArrayBufferViews.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, or Uint8Array to convert
+ * @param encoder - Optional TextEncoder instance (uses singleton if not provided)
+ * @returns Uint8Array representation of the input
+ */
 export function to_uint8(input: CoerceBinaryInput, encoder?: TextEncoder): Uint8Array {
   if (typeof input === "string") {
     return (encoder ?? TxtEnDecoderSingleton()).encode(input);
   }
-  if (input instanceof ArrayBuffer /* || input instanceof SharedArrayBuffer */) {
+  if (isArrayBuffer(input)) {
     return new Uint8Array(input);
   }
 
-  if (input instanceof Uint8Array) {
+  if (isUint8Array(input)) {
     return input;
   }
   // not nice but we make the cloudflare types happy
   return new Uint8Array(input as unknown as ArrayBufferLike);
 }
 
+/**
+ * Converts various binary input types to Blob.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, Uint8Array, or Blob to convert
+ * @param encoder - Optional TextEncoder instance (uses singleton if not provided)
+ * @returns Blob representation of the input
+ */
 export function to_blob(input: CoerceBinaryInput | Blob, encoder?: TextEncoder): Blob {
   if (input instanceof Blob) {
     return input;
@@ -32,6 +74,13 @@ export function to_blob(input: CoerceBinaryInput | Blob, encoder?: TextEncoder):
   return new Blob([ab]);
 }
 
+/**
+ * Converts various binary input types to ArrayBuffer.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, or Uint8Array to convert
+ * @param encoder - Optional TextEncoder instance (uses singleton if not provided)
+ * @returns ArrayBuffer representation of the input
+ */
 export function to_arraybuf(input: CoerceBinaryInput, encoder?: TextEncoder): ArrayBuffer {
   if (input instanceof ArrayBuffer) {
     return input;

package/src/crypto.ts

@@ -123,11 +123,45 @@ function digestSHA256(crypto: typeof globalThis.crypto): (data: Uint8Array) => P
   };
 }
 
+/**
+ * Creates a CryptoRuntime abstraction with optional custom implementations.
+ *
+ * Provides a unified crypto interface that works across different JavaScript
+ * runtimes (browsers, Node.js, Deno, CF Workers). Automatically uses the global
+ * Web Crypto API when available, with fallback implementations that throw errors
+ * for unavailable operations. Allows overriding any method for testing or
+ * custom implementations.
+ *
+ * @param cryptoOpts - Optional custom implementations for crypto operations
+ * @returns CryptoRuntime instance with crypto operations
+ *
+ * @example
+ * ```typescript
+ * // Use default global crypto
+ * const crypto = toCryptoRuntime();
+ * const hash = await crypto.digestSHA256(new Uint8Array([1, 2, 3]));
+ * const randomData = crypto.randomBytes(16);
+ *
+ * // Override for testing
+ * const mockCrypto = toCryptoRuntime({
+ *   randomBytes: (size) => new Uint8Array(size).fill(42),
+ *   digestSHA256: async (data) => new ArrayBuffer(32)
+ * });
+ *
+ * // Encrypt/decrypt with AES-GCM
+ * const key = await crypto.importKey(
+ *   'raw',
+ *   new Uint8Array(32),
+ *   { name: 'AES-GCM' },
+ *   false,
+ *   ['encrypt', 'decrypt']
+ * );
+ * ```
+ */
 export function toCryptoRuntime(cryptoOpts: Partial<CryptoRuntime> = {}): CryptoRuntime {
   let crypto: typeof globalThis.crypto;
   if (!globalThis.crypto || !globalThis.crypto.subtle) {
     crypto = {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
       getRandomValues: globalThis.crypto.getRandomValues.bind(globalThis.crypto),
       subtle: {
         importKey: (): Promise<CTCryptoKey> => {

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

@@ -0,0 +1,45 @@
+/// <reference types="deno" />
+
+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 { TxtEnDecoderSingleton } from "../txt-en-decoder.js";
+
+export class DenoRuntimeService implements BasicRuntimeService {
+  readonly _envFactory: EnvFactory;
+  constructor(envFactory: EnvFactory) {
+    this._envFactory = envFactory;
+  }
+  Env(): Env {
+    return this._envFactory();
+  }
+
+  Args(): string[] {
+    return Deno.args;
+  }
+
+  Stdout(): WritableStream<Uint8Array> {
+    return Deno.stdout.writable;
+  }
+  Stderr(): WritableStream<Uint8Array> {
+    return Deno.stderr.writable;
+  }
+}
+
+let baseBasicSysAbstraction: BaseBasicSysAbstraction | undefined = undefined;
+export function DenoBasicSysAbstraction(param: Partial<BaseBasicRuntimeSysAbstractionParams> = {}): BasicSysAbstraction {
+  const ende = param.TxtEnDecoder ?? TxtEnDecoderSingleton();
+  baseBasicSysAbstraction =
+    baseBasicSysAbstraction ??
+    new BaseBasicSysAbstraction({
+      TxtEnDecoder: ende,
+    });
+  return new WrapperBasicSysAbstraction(baseBasicSysAbstraction, {
+    basicRuntimeService: new DenoRuntimeService(envFactory),
+    ...param,
+  });
+}

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

@@ -0,0 +1,57 @@
+import { runtimeFn } from "../runtime.js";
+import { Env, EnvActions, EnvFactoryOpts } from "../sys-env.js";
+
+interface DenoEnv {
+  get: (key: string) => string | undefined;
+  toObject: () => Record<string, string>;
+  set: (key: string, value: string) => void;
+  has: (key: string) => boolean;
+  delete: (key: string) => void;
+}
+
+let once: DenoEnvActions | undefined = undefined;
+export class DenoEnvActions implements EnvActions {
+  readonly #deno = globalThis as unknown as {
+    Deno: {
+      env: DenoEnv;
+    };
+  };
+
+  static new(opts: Partial<EnvFactoryOpts>): EnvActions {
+    once = once ?? new DenoEnvActions(opts);
+    return once;
+  }
+
+  get _env(): DenoEnv {
+    return this.#deno.Deno.env;
+  }
+
+  readonly opts: Partial<EnvFactoryOpts>;
+  private constructor(opts: Partial<EnvFactoryOpts>) {
+    this.opts = opts;
+  }
+
+  register(env: Env): Env {
+    for (const key of env.keys()) {
+      this._env.set(key, env.get(key) || "");
+    }
+    return env;
+  }
+  active(): boolean {
+    return runtimeFn().isDeno;
+  }
+  keys(): string[] {
+    return Object.keys(this._env.toObject());
+  }
+  get(key: string): string | undefined {
+    return this._env.get(key);
+  }
+  set(key: string, value?: string): void {
+    if (value) {
+      this._env.set(key, value);
+    }
+  }
+  delete(key: string): void {
+    this._env.delete(key);
+  }
+}

package/src/deno-env/index.ts

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

package/src/deno-fs/deno-basic-sys-abstraction.ts

@@ -0,0 +1,45 @@
+/// <reference types="deno" />
+
+import type {
+  BasicRuntimeService,
+  Env,
+  BasicSysAbstraction,
+  EnvFactory,
+  BaseBasicSysAbstraction,
+  WithCementWrapperSysAbstractionParams,
+} from "@adviser/cement";
+
+export class DenoRuntimeService implements BasicRuntimeService {
+  readonly _envFactory: EnvFactory;
+  constructor(envFactory: EnvFactory) {
+    this._envFactory = envFactory;
+  }
+  Env(): Env {
+    return this._envFactory();
+  }
+
+  Args(): string[] {
+    return Deno.args;
+  }
+
+  Stdout(): WritableStream<Uint8Array> {
+    return Deno.stdout.writable;
+  }
+  Stderr(): WritableStream<Uint8Array> {
+    return Deno.stderr.writable;
+  }
+}
+
+let baseBasicSysAbstraction: BaseBasicSysAbstraction | undefined = undefined;
+export function DenoBasicSysAbstraction(param: WithCementWrapperSysAbstractionParams): BasicSysAbstraction {
+  const ende = param.TxtEnDecoder ?? param.cement.TxtEnDecoderSingleton();
+  baseBasicSysAbstraction =
+    baseBasicSysAbstraction ??
+    new param.cement.BaseBasicSysAbstraction({
+      TxtEnDecoder: ende,
+    });
+  return new param.cement.WrapperBasicSysAbstraction(baseBasicSysAbstraction, {
+    basicRuntimeService: new DenoRuntimeService(param?.cement.envFactory),
+    ...param,
+  });
+}

package/src/deno-fs/deno-env-actions.ts

@@ -0,0 +1,56 @@
+import type { Env, EnvActions, EnvFactoryOpts, WithCement } from "@adviser/cement";
+
+interface DenoEnv {
+  get: (key: string) => string | undefined;
+  toObject: () => Record<string, string>;
+  set: (key: string, value: string) => void;
+  has: (key: string) => boolean;
+  delete: (key: string) => void;
+}
+
+let once: DenoEnvActions | undefined = undefined;
+export class DenoEnvActions implements EnvActions {
+  readonly #deno = globalThis as unknown as {
+    Deno: {
+      env: DenoEnv;
+    };
+  };
+
+  static new(opts: WithCement<Partial<EnvFactoryOpts>>): EnvActions {
+    once = once ?? new DenoEnvActions(opts);
+    return once;
+  }
+
+  get _env(): DenoEnv {
+    return this.#deno.Deno.env;
+  }
+
+  readonly opts: WithCement<Partial<EnvFactoryOpts>>;
+  private constructor(opts: WithCement<Partial<EnvFactoryOpts>>) {
+    this.opts = opts;
+  }
+
+  register(env: Env): Env {
+    for (const key of env.keys()) {
+      this._env.set(key, env.get(key) || "");
+    }
+    return env;
+  }
+  active(): boolean {
+    return this.opts.cement.runtimeFn().isDeno;
+  }
+  keys(): string[] {
+    return Object.keys(this._env.toObject());
+  }
+  get(key: string): string | undefined {
+    return this._env.get(key);
+  }
+  set(key: string, value?: string): void {
+    if (value) {
+      this._env.set(key, value);
+    }
+  }
+  delete(key: string): void {
+    this._env.delete(key);
+  }
+}

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

@@ -0,0 +1,91 @@
+import * as path from "node:path";
+import type { FileService, NamedWritableStream, TxtEnDecoder } from "@adviser/cement";
+
+const Deno = (globalThis as unknown as { Deno: unknown }).Deno as {
+  cwd(): string;
+  readFile(fname: string): Promise<Uint8Array>;
+  mkdir(base: string, options: { recursive: boolean }): Promise<void>;
+  open(fname: string, options: { write: boolean; create: boolean; truncate: boolean }): Promise<WritableStream<Uint8Array>>;
+};
+
+export class DenoFileService implements FileService {
+  readonly baseDir: string;
+  readonly txtEnde: TxtEnDecoder;
+  constructor(txtEnde: TxtEnDecoder, baseDir: string = Deno.cwd()) {
+    this.baseDir = this.abs(baseDir);
+    this.txtEnde = txtEnde;
+  }
+
+  // nodeImport(fname: string): string {
+  //   // console.log('nodeImport:'+ fname);
+  //   if (path.isAbsolute(fname)) {
+  //     return fname;
+  //   } else {
+  //     return "./" + path.normalize(fname);
+  //   }
+  // }
+
+  async readFileString(fname: string): Promise<string> {
+    return this.txtEnde.decode(await Deno.readFile(fname));
+  }
+
+  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 = Deno.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 = Deno.cwd();
+      return path.resolve(cwd, fname);
+    }
+  }
+
+  isAbsolute(fname: string): boolean {
+    return path.isAbsolute(fname);
+  }
+
+  async writeFileString(fname: string, content: string, ende: TxtEnDecoder = this.txtEnde): 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 Deno.mkdir(base, { recursive: true });
+    const out = await Deno.open(oName, {
+      write: true,
+      create: true,
+      truncate: true,
+    });
+    return {
+      name: oName,
+      stream: out,
+    };
+  }
+}

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

@@ -0,0 +1,130 @@
+import type {
+  ExitService,
+  ExitHandler,
+  BaseSysAbstraction,
+  RuntimeSysAbstraction,
+  SystemService,
+  VoidFunc,
+  WithCementWrapperSysAbstractionParams,
+} from "@adviser/cement";
+import { DenoBasicSysAbstraction } from "./deno-basic-sys-abstraction.js";
+// import * as process from "node:process";
+import { DenoFileService } from "./deno-file-service.js";
+
+const Deno = (globalThis as unknown as { Deno: unknown }).Deno as {
+  addSignalListener(sig: string, hdl: () => void): void;
+  exit(code?: number): void;
+  args: string[];
+};
+
+export class DenoExitServiceImpl implements ExitService {
+  constructor() {
+    globalThis.addEventListener("unhandledrejection", (e) => {
+      e.preventDefault();
+      this.exit(19);
+    });
+    globalThis.addEventListener("error", () => {
+      this.exit(19);
+    });
+    globalThis.addEventListener("uncaughtException", () => {
+      this.exit(19);
+    });
+
+    // process.on("close", () => {
+    //   this.exit(0);
+    // });
+    globalThis.addEventListener("unload", () => {
+      this.exit(0);
+      // console.log('goodbye!');
+    });
+
+    // process.on("exit", () => {
+    // });
+    Deno.addSignalListener("SIGQUIT", () => {
+      this.exit(3);
+    });
+    Deno.addSignalListener("SIGINT", () => {
+      this.exit(2);
+    });
+    Deno.addSignalListener("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(() => {
+        Deno.exit(code);
+      })
+      .catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error("ExitService: failed to handle exit", err);
+        Deno.exit(code);
+      });
+  }
+}
+
+export class DenoSystemService implements SystemService {
+  static readonly _exitHandlers: ExitHandler[] = [];
+  readonly _exitService: ExitService = new DenoExitServiceImpl();
+  constructor() {
+    this._exitService.injectExitHandlers(DenoSystemService._exitHandlers);
+  }
+
+  OnExit(hdl: VoidFunc): VoidFunc {
+    const id = crypto.randomUUID();
+    DenoSystemService._exitHandlers.push({ hdl, id });
+    return () => {
+      const idx = DenoSystemService._exitHandlers.findIndex((h) => h.id === id);
+      if (idx >= 0) {
+        DenoSystemService._exitHandlers.splice(idx, 1);
+      }
+    };
+  }
+
+  Exit(code: number): void {
+    this._exitService.exit(code);
+  }
+}
+
+let baseSysAbstraction: BaseSysAbstraction | undefined = undefined;
+export function DenoSysAbstraction(param: WithCementWrapperSysAbstractionParams): RuntimeSysAbstraction {
+  const ende = param?.TxtEnDecoder ?? param.cement.TxtEnDecoderSingleton();
+  baseSysAbstraction =
+    baseSysAbstraction ??
+    new param.cement.BaseSysAbstraction({
+      TxtEnDecoder: ende,
+      FileSystem: new DenoFileService(ende),
+      SystemService: new DenoSystemService(),
+    });
+  return new param.cement.WrapperRuntimeSysAbstraction(baseSysAbstraction, {
+    basicRuntimeService: DenoBasicSysAbstraction(param),
+    ...param,
+  });
+}

package/src/deno-fs/index.ts

@@ -0,0 +1,4 @@
+export * from "./deno-sys-abstraction.js";
+export * from "./deno-file-service.js";
+export * from "./deno-env-actions.js";
+export * from "./deno-basic-sys-abstraction.js";