@cyberismo/data-handler 0.0.20 → 0.0.22

package/src/utils/handlebars-helpers.ts

@@ -0,0 +1,95 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import type Handlebars from 'handlebars';
+import { escapeJsonString } from './json.js';
+import { escapeCsvField } from './csv.js';
+import { resourceName } from './resource-utils.js';
+
+/**
+ * Formats a value from a logic program for use in graphviz
+ * @param value - The value to format
+ * @returns The formatted value
+ */
+function formatAttributeValue(value?: string) {
+  if (!value) {
+    return '';
+  }
+  // value is an html-like string
+  if (value.length > 1 && value.startsWith('<') && value.endsWith('>')) {
+    return value;
+  }
+  // value is a normal string and needs to be wrapped in quotes
+  return `"${value}"`;
+}
+
+/**
+ * Checks if a field is a custom field
+ * @param field - The field to check
+ * @returns True if the field is a custom field, false otherwise
+ */
+function isCustomField(field: string) {
+  try {
+    const { type } = resourceName(field, true);
+    return type === 'fieldTypes';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Formats a value for display in a report
+ * @param value - The value to format
+ * @returns The formatted value
+ */
+function formatValue(value: unknown): string {
+  if (typeof value === 'object') {
+    if (Array.isArray(value)) {
+      return value.map((v) => formatValue(v)).join(', ');
+    }
+    if (
+      value != null &&
+      'displayValue' in value &&
+      typeof value.displayValue === 'string'
+    ) {
+      return value.displayValue;
+    }
+    if (value != null && 'value' in value && typeof value.value === 'string') {
+      return formatValue(value.value);
+    }
+    return JSON.stringify(value, null, 2);
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'Yes' : 'No';
+  }
+  return value?.toString() ?? '';
+}
+
+/**
+ * Registers comparison helpers (eq and ne) with a Handlebars instance
+ * @param instance handlebars instance
+ */
+export function registerComparisonHelpers(instance: typeof Handlebars) {
+  instance.registerHelper('eq', (a: unknown, b: unknown) => a === b);
+  instance.registerHelper('ne', (a: unknown, b: unknown) => a !== b);
+}
+
+/**
+ * Registers report-specific helpers with a Handlebars instance
+ * @param instance handlebars instance
+ */
+export function registerReportHelpers(instance: typeof Handlebars) {
+  instance.registerHelper('formatAttributeValue', formatAttributeValue);
+  instance.registerHelper('isCustomField', isCustomField);
+  instance.registerHelper('formatValue', formatValue);
+  instance.registerHelper('jsonEscape', escapeJsonString);
+  instance.registerHelper('csvEscape', escapeCsvField);
+}

package/src/utils/json.ts

@@ -15,6 +15,29 @@
 import { readFileSync } from 'node:fs';
 import { type FileHandle, readFile, writeFile } from 'node:fs/promises';
 
+/**
+ * Escapes a string for use as a JSON string value.
+ * Escapes double quotes, backslashes, and control characters.
+ * @param content The string to escape
+ * @returns The escaped string suitable for use in JSON
+ */
+export function escapeJsonString(content: string): string {
+  return JSON.stringify(content).slice(1, -1);
+}
+
+/**
+ * Format an object with JSON.stringify
+ *
+ * The purpose of this function is to format the JSON output in a centralised function
+ * so that the format can be controlled in a single location.
+ *
+ * @param json JSON object to format.
+ * @returns Formatted JSON string
+ */
+export function formatJson(json: object) {
+  return JSON.stringify(json, trimReplacer, 4);
+}
+
 /**
  * Handles reading of a JSON file.
  * @param file file name (and path) to read.
@@ -28,7 +51,9 @@ export function readJsonFileSync(file: string) {
     return returnValue;
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(`Invalid JSON in file '${file}': ${error.message}`);
+      throw new Error(`Invalid JSON in file '${file}': ${error.message}`, {
+        cause: error,
+      });
     }
   }
 }
@@ -45,7 +70,9 @@ export async function readJsonFile(file: string) {
     return JSON.parse(raw);
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(`Invalid JSON in file '${file}': ${error.message}`);
+      throw new Error(`Invalid JSON in file '${file}': ${error.message}`, {
+        cause: error,
+      });
     }
   }
 }
@@ -79,19 +106,6 @@ export function trimReplacer(_: string, value: unknown) {
   return value;
 }
 
-/**
- * Format an object with JSON.stringify
- *
- * The purpose of this function is to format the JSON output in a centralised function
- * so that the format can be controlled in a single location.
- *
- * @param json JSON object to format.
- * @returns Formatted JSON string
- */
-export function formatJson(json: object) {
-  return JSON.stringify(json, trimReplacer, 4);
-}
-
 /**
  * Writes and formats a JSON file.
  * @param filename file name (and path) to write.

package/src/utils/log-utils.ts

@@ -9,15 +9,44 @@
     You should have received a copy of the GNU Affero General Public
     License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import pino, { type ChildLoggerOptions, type Logger } from 'pino';
+import pino, { type Level, type ChildLoggerOptions, type Logger } from 'pino';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 
 // This could be also a more generic interface, but since we use pino and this is an internal package, let's keep it simple
-// silent logger as default
+// Silent logger as default.
 let _logger: Logger = pino({ level: 'silent' });
+let initialized = false;
 
-export function setLogger(logger: Logger) {
-  _logger = logger;
+/**
+ * Initialize the logger
+ * @param level Log level for stdout output.
+ * @param logPath Optional file path for full trace logging.
+ */
+export function initLogger(level: Level, logPath?: string): void {
+  if (initialized) return;
+  initialized = true;
+  if (logPath) {
+    try {
+      mkdirSync(dirname(logPath), { recursive: true });
+    } catch (error) {
+      throw new Error(
+        `Failed to create log directory '${dirname(logPath)}': ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    _logger = pino(
+      { level: 'trace' },
+      pino.multistream([
+        { stream: pino.destination(logPath), level: 'trace' },
+        { stream: pino.destination(1), level },
+      ]),
+    );
+  } else {
+    _logger = pino({ level }, pino.destination(1));
+  }
 }
+
 /**
  * Returns the logger instance.
  */

package/src/utils/report.ts

@@ -13,65 +13,10 @@ import Handlebars from 'handlebars';
 import type { CalculationEngine } from '../containers/project/calculation-engine.js';
 import { registerEmptyMacros } from '../macros/index.js';
 import type { Context } from '../interfaces/project-interfaces.js';
-import { resourceName } from './resource-utils.js';
-
-/**
- * Formats a value from a logic program for use to graphviz
- * @param value - The value to format
- * @returns The formatted value
- */
-export function formatAttributeValue(value?: string) {
-  if (!value) {
-    return '';
-  }
-  // value is an html-like string
-  if (value.length > 1 && value.startsWith('<') && value.endsWith('>')) {
-    return value;
-  }
-  // value is a normal string and needs to be wrapped in quotes
-  return `"${value}"`;
-}
-
-/**
- * Checks if a field is a custom field
- * @param field - The field to check
- * @returns True if the field is a custom field, false otherwise
- */
-export function isCustomField(field: string) {
-  try {
-    const { type } = resourceName(field, true);
-    return type === 'fieldTypes';
-  } catch {
-    return false;
-  }
-}
-/**
- * Formats a value for display in a report
- * @param value - The value to format
- * @returns The formatted value
- */
-export function formatValue(value: unknown): string {
-  if (typeof value === 'object') {
-    if (Array.isArray(value)) {
-      return value.map((v) => formatValue(v)).join(', ');
-    }
-    if (
-      value != null &&
-      'displayValue' in value &&
-      typeof value.displayValue === 'string'
-    ) {
-      return value.displayValue;
-    }
-    if (value != null && 'value' in value && typeof value.value === 'string') {
-      return formatValue(value.value);
-    }
-    return JSON.stringify(value, null, 2);
-  }
-  if (typeof value === 'boolean') {
-    return value ? 'Yes' : 'No';
-  }
-  return value?.toString() ?? '';
-}
+import {
+  registerComparisonHelpers,
+  registerReportHelpers,
+} from './handlebars-helpers.js';
 
 /**
  * Parameters for the core generation function
@@ -81,7 +26,6 @@ interface GenerateReportContentParams {
   contentTemplate: string;
   queryTemplate: string;
   options: Record<string, string | undefined | boolean>;
-  graph?: boolean;
   context: Context;
 }
 
@@ -96,16 +40,11 @@ interface GenerateReportContentParams {
 export async function generateReportContent(
   params: GenerateReportContentParams,
 ): Promise<string> {
-  const {
-    calculate,
-    contentTemplate,
-    queryTemplate,
-    graph,
-    options, // Destructure options
-    context,
-  } = params;
+  const { calculate, contentTemplate, queryTemplate, options, context } =
+    params;
 
   const handlebars = Handlebars.create();
+  registerComparisonHelpers(handlebars);
 
   // Compile and execute the query template
   const template = handlebars.compile(queryTemplate, {
@@ -119,12 +58,7 @@ export async function generateReportContent(
   }
   // register empty macros so that other macros aren't touched yet
   registerEmptyMacros(handlebars);
-
-  if (graph) {
-    handlebars.registerHelper('formatAttributeValue', formatAttributeValue);
-  }
-  handlebars.registerHelper('isCustomField', isCustomField);
-  handlebars.registerHelper('formatValue', formatValue);
+  registerReportHelpers(handlebars);
 
   return handlebars.compile(contentTemplate)({
     ...options,

package/src/utils/rw-lock.ts

@@ -0,0 +1,279 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2026
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { runWithDefaultCommitMessage } from './commit-context.js';
+import { getChildLogger } from './log-utils.js';
+
+interface LockContext {
+  mode: 'read' | 'write';
+  active: boolean;
+}
+
+/**
+ * Promise-based read-write lock with writer priority and reentrancy.
+ *
+ * - Multiple concurrent readers are allowed.
+ * - Writers get exclusive access.
+ * - Writer-priority: new readers block when a writer is waiting.
+ * - Reentrancy via AsyncLocalStorage: nested lock calls within the same
+ *   async context are no-ops.
+ * - After-write hooks fire after the outermost write completes successfully.
+ */
+export class RWLock {
+  private readers = 0;
+  private writer = false;
+  private readerQueue: (() => void)[] = [];
+  private writerQueue: (() => void)[] = [];
+  private context = new AsyncLocalStorage<LockContext>();
+  private afterWriteHooks: (() => Promise<void>)[] = [];
+  private writeErrorHooks: ((error: unknown) => Promise<void>)[] = [];
+  private readonly logger;
+
+  constructor(private readonly name: string = 'RWLock') {
+    this.logger = getChildLogger({ module: 'RWLock', name });
+  }
+
+  /**
+   * Register a callback that fires after the outermost write completes
+   * successfully. Hooks run while still holding the write lock.
+   */
+  onAfterWrite(hook: () => Promise<void>): void {
+    this.afterWriteHooks.push(hook);
+  }
+
+  /**
+   * Register a callback that fires when the outermost write fails.
+   * Hooks run while still holding the write lock.
+   */
+  onWriteError(hook: (error: unknown) => Promise<void>): void {
+    this.writeErrorHooks.push(hook);
+  }
+
+  /**
+   * Execute `fn` under a read lock. Concurrent readers are allowed.
+   * If already inside a read or write context, just runs fn directly.
+   */
+  async read<T>(fn: () => Promise<T>): Promise<T> {
+    const current = this.context.getStore();
+    if (current?.active) {
+      return fn();
+    }
+
+    await this.acquireRead();
+    const ctx: LockContext = { mode: 'read', active: true };
+    try {
+      return await this.context.run(ctx, fn);
+    } finally {
+      ctx.active = false;
+      this.releaseRead();
+    }
+  }
+
+  /**
+   * Execute `fn` under an exclusive write lock.
+   * If already inside a write context, just runs fn directly (no hooks).
+   */
+  async write<T>(fn: () => Promise<T>): Promise<T> {
+    const current = this.context.getStore();
+    if (current?.active && current.mode === 'write') {
+      return fn();
+    }
+    if (current?.active && current.mode === 'read') {
+      throw new Error('Cannot acquire write lock while holding read lock');
+    }
+
+    await this.acquireWrite();
+    const ctx: LockContext = { mode: 'write', active: true };
+    try {
+      const result = await this.context.run(ctx, fn);
+      // Fire after-write hooks while still holding the lock
+      for (const hook of this.afterWriteHooks) {
+        await this.context.run(ctx, hook);
+      }
+      return result;
+    } catch (error) {
+      // Run rollback hooks on error (outermost write only)
+      for (const hook of this.writeErrorHooks) {
+        await this.context.run(ctx, () => hook(error));
+      }
+      throw error;
+    } finally {
+      ctx.active = false;
+      this.releaseWrite();
+    }
+  }
+
+  private acquireRead(): Promise<void> {
+    if (!this.writer && this.writerQueue.length === 0) {
+      this.readers++;
+      this.logger.trace({ readers: this.readers }, 'read lock acquired');
+      return Promise.resolve();
+    }
+    this.logger.debug(
+      {
+        readers: this.readers,
+        writer: this.writer,
+        writerQueueDepth: this.writerQueue.length,
+        readerQueueDepth: this.readerQueue.length,
+      },
+      'read lock queued (writer active or pending)',
+    );
+    return new Promise<void>((resolve) => {
+      this.readerQueue.push(() => {
+        this.readers++;
+        this.logger.debug(
+          {
+            readers: this.readers,
+            writerQueueDepth: this.writerQueue.length,
+            readerQueueDepth: this.readerQueue.length,
+          },
+          'read lock acquired after wait',
+        );
+        resolve();
+      });
+    });
+  }
+
+  private releaseRead(): void {
+    this.readers--;
+    this.logger.trace(
+      {
+        readers: this.readers,
+        writerQueueDepth: this.writerQueue.length,
+        readerQueueDepth: this.readerQueue.length,
+      },
+      'read lock released',
+    );
+    if (this.readers === 0 && this.writerQueue.length > 0) {
+      const next = this.writerQueue.shift()!;
+      next();
+    }
+  }
+
+  private acquireWrite(): Promise<void> {
+    if (!this.writer && this.readers === 0) {
+      this.writer = true;
+      this.logger.trace(
+        {
+          readers: this.readers,
+          writerQueueDepth: this.writerQueue.length,
+          readerQueueDepth: this.readerQueue.length,
+        },
+        'write lock acquired',
+      );
+      return Promise.resolve();
+    }
+    this.logger.debug(
+      {
+        readers: this.readers,
+        writer: this.writer,
+        writerQueueDepth: this.writerQueue.length,
+        readerQueueDepth: this.readerQueue.length,
+      },
+      `write lock queued (readers: ${this.readers}, writer active: ${this.writer})`,
+    );
+    return new Promise<void>((resolve) => {
+      this.writerQueue.push(() => {
+        this.writer = true;
+        this.logger.debug(
+          {
+            readers: this.readers,
+            writerQueueDepth: this.writerQueue.length,
+            readerQueueDepth: this.readerQueue.length,
+          },
+          'write lock acquired after wait',
+        );
+        resolve();
+      });
+    });
+  }
+
+  private releaseWrite(): void {
+    this.writer = false;
+    this.logger.trace(
+      {
+        readers: this.readers,
+        writerQueueDepth: this.writerQueue.length,
+        readerQueueDepth: this.readerQueue.length,
+      },
+      'write lock released',
+    );
+    if (this.writerQueue.length > 0) {
+      const next = this.writerQueue.shift()!;
+      next();
+    } else {
+      // Wake ALL waiting readers
+      const readers = this.readerQueue.splice(0);
+      for (const wake of readers) {
+        wake();
+      }
+    }
+  }
+}
+
+// Helper to access the lock from a command instance via its `project` property.
+function getLock(instance: object): RWLock {
+  const lock = (instance as { project?: { lock?: RWLock } }).project?.lock;
+  if (!lock) {
+    throw new Error(
+      '@read/@write decorator: instance.project.lock is not defined. ' +
+        'Ensure the class has a `project` property with `lock: RWLock`.',
+    );
+  }
+  return lock;
+}
+
+/**
+ * A Helper decorator built for commands that automatically handles using a read lock
+ */
+export function read<This extends object, Args extends unknown[], Return>(
+  target: (this: This, ...args: Args) => Promise<Return>,
+): (this: This, ...args: Args) => Promise<Return> {
+  return function (this: This, ...args: Args): Promise<Return> {
+    return getLock(this).read(() => target.call(this, ...args));
+  };
+}
+
+/**
+ * A Helper decorator built for commands that automatically handles using a write lock.
+ *
+ * Two forms:
+ * - `@write()`: just acquires the write lock, no commit message (for wrapper methods)
+ * - `@write((param) => \`Do ${param}\`)`: acquires the write lock and sets a default commit message
+ */
+export function write<This extends object, Args extends unknown[], Return>(): (
+  target: (this: This, ...args: Args) => Promise<Return>,
+) => (this: This, ...args: Args) => Promise<Return>;
+
+export function write<This extends object, Args extends unknown[], Return>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  message: (...args: any[]) => string,
+): (
+  target: (this: This, ...args: Args) => Promise<Return>,
+) => (this: This, ...args: Args) => Promise<Return>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function write(message?: (...args: any[]) => string): unknown {
+  return function (target: (...args: unknown[]) => Promise<unknown>) {
+    return function (this: object, ...args: unknown[]) {
+      if (!message) {
+        return getLock(this).write(() => target.call(this, ...args));
+      }
+      const label = message(...args);
+      return runWithDefaultCommitMessage(label, () =>
+        getLock(this).write(() => target.call(this, ...args)),
+      );
+    };
+  };
+}

package/src/utils/user-preferences.ts

@@ -117,6 +117,7 @@ export class UserPreferences {
         if (error.code !== 'EEXIST') {
           throw new Error(
             `Error creating preferences file '${this.prefsFilePath}': ${error}`,
+            { cause: error },
           );
         } else {
           this.logger.warn('Preferences file already exists');
@@ -124,6 +125,7 @@ export class UserPreferences {
       } else {
         throw new Error(
           `Error creating preferences file '${this.prefsFilePath}': ${error}`,
+          { cause: error },
         );
       }
     }
@@ -142,6 +144,7 @@ export class UserPreferences {
     } catch (error) {
       throw new Error(
         `Error reading preferences file '${this.prefsFilePath}': ${error}`,
+        { cause: error },
       );
     }
   }