@comake/skl-js-engine 1.3.9 → 1.3.10

package/src/logger.ts

@@ -0,0 +1,144 @@
+import { inspect } from 'util';
+
+export interface LoggerOptions {
+  maxStringLength?: number;
+  maxArrayItems?: number;
+}
+
+export class Logger {
+  private static instance: Logger;
+  private readonly isDebug: boolean;
+  private metadata: Record<string, any>;
+
+  // Maximum characters to keep for long strings
+  private readonly maxStringLength: number;
+  // Maximum number of items to show for long arrays
+  private readonly maxArrayItems: number;
+
+  private constructor(isDebug: boolean, metadata: Record<string, any>, options?: LoggerOptions) {
+    this.isDebug = true;
+    this.metadata = metadata;
+    this.maxStringLength = options?.maxStringLength ?? 2_000;
+    this.maxArrayItems = options?.maxArrayItems ?? 10;
+  }
+
+  /**
+   * Returns a singleton instance of the logger. The logger honours the DEBUG env variable unless
+   * explicitly overridden via the `isDebug` parameter.
+   */
+  public static getInstance(isDebug?: boolean, metadata?: Record<string, any>, options?: LoggerOptions): Logger {
+    if (!Logger.instance) {
+      // eslint-disable-next-line no-process-env
+      const debugEnabled = isDebug ?? process.env.DEBUG === 'true';
+      Logger.instance = new Logger(debugEnabled, metadata ?? {}, options);
+    }
+    return Logger.instance;
+  }
+
+  /**
+   * Merges the given metadata with the existing metadata attached to the logger.
+   */
+  public setMetadata(metadata: Record<string, any>): void {
+    this.metadata = { ...this.metadata, ...metadata };
+  }
+
+  public getMetadataString(): string | undefined {
+    if (!this.metadata || Object.keys(this.metadata).length === 0) {
+      return undefined;
+    }
+    return JSON.stringify(this.metadata);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public logging APIs
+  // ---------------------------------------------------------------------------
+
+  public log(...args: any[]): void {
+    if (this.isDebug) {
+      const metadataString = this.getMetadataString();
+      const logArgs = metadataString ? [ ...this.formatArgs(args), metadataString ] : this.formatArgs(args);
+      // eslint-disable-next-line no-console
+      console.log(...logArgs);
+    }
+  }
+
+  public error(...args: any[]): void {
+    if (this.isDebug) {
+      const metadataString = this.getMetadataString();
+      const logArgs = metadataString ? [ ...this.formatArgs(args), metadataString ] : this.formatArgs(args);
+      // eslint-disable-next-line no-console
+      console.error(...logArgs);
+    }
+  }
+
+  public debug(...args: any[]): void {
+    if (this.isDebug) {
+      const metadataString = this.getMetadataString();
+      const logArgs = metadataString ? [ ...this.formatArgs(args), metadataString ] : this.formatArgs(args);
+      // eslint-disable-next-line no-console
+      console.debug(...logArgs);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Applies safe formatting to every argument before it is passed to the console. Large strings are
+   * truncated, large arrays/objects are abbreviated and circular references are handled gracefully
+   * by `util.inspect`.
+   */
+  private formatArgs(args: any[]): any[] {
+    return args.map((arg: any): any => this.formatValue(arg));
+  }
+
+  private formatValue(value: any): any {
+    try {
+      if (typeof value === 'string') {
+        return this.truncateString(value);
+      }
+
+      if (Array.isArray(value)) {
+        return JSON.stringify(this.truncateArray(value));
+      }
+
+      if (typeof value === 'object' && value !== null) {
+        // For objects we rely on util.inspect which gives us fine-grained control over depth,
+        // array length and string length.
+        return inspect(value, {
+          depth: 6,
+          maxArrayLength: this.maxArrayItems,
+          maxStringLength: this.maxStringLength,
+          breakLength: 120,
+          compact: false,
+          colors: true
+        });
+      }
+
+      // Primitives, functions, etc. are returned as-is.
+      return value;
+    } catch (err: unknown) {
+      // In the unlikely event that formatting fails, fall back to a best-effort stringify.
+      // eslint-disable-next-line no-console
+      console.warn('Logger: failed to format value', err);
+      return String(value);
+    }
+  }
+
+  private truncateString(str: string): string {
+    if (str.length <= this.maxStringLength) {
+      return str;
+    }
+    return `${str.slice(0, this.maxStringLength)}...(truncated ${str.length - this.maxStringLength} chars)`;
+  }
+
+  private truncateArray(arr: any[]): any[] {
+    if (arr.length <= this.maxArrayItems) {
+      return arr.map((item: any): any => this.formatValue(item));
+    }
+
+    const displayedItems = arr.slice(0, this.maxArrayItems).map((item: any): any => this.formatValue(item));
+    return [ ...displayedItems, `...(truncated ${arr.length - this.maxArrayItems} items)` ];
+  }
+}

package/src/mapping/Mapper.ts

@@ -0,0 +1,52 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import * as RmlParser from '@comake/rmlmapper-js';
+import type { NodeObject } from 'jsonld';
+import jsonld from 'jsonld';
+import type { JSONValue, OrArray } from '../util/Types';
+
+export interface MapperArgs {
+  functions?: Record<string, (args: any | any[]) => any>;
+}
+
+export class Mapper {
+  private readonly functions?: Record<string, (args: any | any[]) => any>;
+
+  public constructor(args?: MapperArgs) {
+    this.functions = args?.functions;
+  }
+
+  public async apply(
+    data: JSONValue,
+    mapping: OrArray<NodeObject>,
+    frame: Record<string, any>
+  ): Promise<NodeObject> {
+    const result = await this.doMapping(data, mapping);
+    const frameResult = await this.frame(result, frame);
+    return frameResult;
+  }
+
+  private async doMapping(data: JSONValue, mapping: OrArray<NodeObject>): Promise<NodeObject[]> {
+    const sources = { 'input.json': JSON.stringify(data) };
+    const options = { functions: this.functions };
+    const mappingNodeObject = Array.isArray(mapping)
+      ? { '@graph': mapping }
+      : mapping;
+    return await RmlParser.parseJsonLd(mappingNodeObject, sources, options) as NodeObject[];
+  }
+
+  private async frame(
+    jsonldDoc: any[],
+    overrideFrame: Record<string, any>
+  ): Promise<NodeObject> {
+    let frame: Record<string, any> = {
+      '@context': {},
+      '@embed': '@always'
+    };
+    frame = {
+      ...frame,
+      ...overrideFrame,
+      '@context': { ...frame['@context'], ...overrideFrame?.['@context'] }
+    };
+    return await jsonld.frame(jsonldDoc, frame);
+  }
+}

package/src/storage/FindOperator.ts

@@ -0,0 +1,55 @@
+import type { Variable } from 'rdf-data-factory';
+
+export type FindOperatorType =
+  | 'in'
+  | 'not'
+  | 'and'
+  | 'equal'
+  | 'exists'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'inverse'
+  | 'inverseRelation'
+  | 'inverseRelationOrder'
+  | 'sequencePath'
+  | 'zeroOrMorePath'
+  | 'inversePath'
+  | 'oneOrMorePath'
+  | 'contains'
+  | 'sequence';
+
+export interface FindOperatorArgs<T, TType> {
+  operator: TType;
+  value?: T | FindOperator<T, any>;
+  subject?: Variable;
+  isOptional?: boolean;
+}
+
+export class FindOperator<T, TType extends FindOperatorType> {
+  public readonly type = 'operator';
+  public readonly operator: TType;
+  public readonly subject?: Variable;
+  public readonly value?: T | FindOperator<T, any>;
+  public readonly isOptional?: boolean;
+  public constructor(args: FindOperatorArgs<T, TType>) {
+    this.operator = args.operator;
+    this.value = args.value;
+    this.subject = args.subject;
+    this.isOptional = args.isOptional;
+  }
+
+  public static isFindOperator(value: any): boolean {
+    return typeof value === 'object' && 'type' in value && value.type === 'operator';
+  }
+
+  public static isPathOperator(operator: FindOperator<any, any>): boolean {
+    return (
+      operator.operator === 'inversePath' ||
+      operator.operator === 'zeroOrMorePath' ||
+      operator.operator === 'sequencePath' ||
+      operator.operator === 'zeroOrMorePath'
+    );
+  }
+}

package/src/storage/FindOptionsTypes.ts

@@ -0,0 +1,107 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import type { Expression, Variable } from 'sparqljs';
+import type { OrArray, JSONArray, JSONObject } from '../util/Types';
+import type { FindOperator } from './FindOperator';
+import type { InverseRelationOperatorValue } from './operator/InverseRelation';
+import type { InverseRelationOrderValue } from './operator/InverseRelationOrder';
+
+export type FindOptionsSelect = string[] | {[key: string]: boolean | FindOptionsSelect };
+
+export interface FindOneOptions {
+  select?: FindOptionsSelect;
+  where?: FindOptionsWhere;
+  relations?: FindOptionsRelations;
+  order?: FindOptionsOrder;
+  skipFraming?: boolean;
+  group?: Variable;
+  entitySelectVariable?: Variable;
+}
+
+export type FindOptionsRelationsValue =
+  | boolean
+  | FindOptionsRelations
+  | FindOperator<InverseRelationOperatorValue, 'inverseRelation'>;
+
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+export type FindOptionsRelations = {
+  [k: string]: FindOptionsRelationsValue;
+};
+
+export type FindOptionsOrderValue = 'ASC' | 'DESC' | 'asc' | 'desc' | 1 | -1;
+
+export type FindOptionsOrder = Record<
+string,
+FindOptionsOrderValue | FindOperator<InverseRelationOrderValue, 'inverseRelationOrder'>
+>;
+
+export type FieldPrimitiveValue = boolean | number | string | Date;
+
+export type JsonValueObject = {
+  '@value': FieldPrimitiveValue | JSONObject | JSONArray;
+  '@type': '@json';
+};
+
+export type LanguageValueObject = {
+  '@value': string;
+  '@language': string;
+  '@direction': string;
+};
+
+export type NonJsonValueObject = {
+  '@value': FieldPrimitiveValue;
+  '@type': string;
+};
+
+export type ValueWhereFieldObject = JsonValueObject | LanguageValueObject | NonJsonValueObject;
+
+export type FindOptionsWhereField =
+  | OrArray<FieldPrimitiveValue>
+  | ValueWhereFieldObject
+  | FindOptionsWhere
+  | OrArray<FindOperator<any, any>>
+  | BindPattern[];
+
+export type IdFindOptionsWhereField = string | FindOperator<any, 'in' | 'not' | 'equal' | 'inversePath' | 'contains'>;
+
+export type TypeFindOptionsWhereField =
+  | string
+  | FindOperator<string | string[] | FindOptionsWhere, 'in' | 'not' | 'equal' | 'inverse' | 'contains'>;
+
+export interface BindPattern {
+  expression: Expression;
+  variable: Variable;
+}
+
+export interface FindOptionsWhere {
+  type?: TypeFindOptionsWhereField;
+  id?: IdFindOptionsWhereField;
+  binds?: BindPattern[];
+  [k: string]: FindOptionsWhereField | BindPattern[] | undefined;
+}
+
+// Add these new types
+export interface SubQuery {
+  select: Variable[];
+  where: FindOptionsWhere;
+  groupBy?: string[];
+  having?: FindOptionsWhere;
+}
+
+export interface FindAllOptions extends FindOneOptions {
+  offset?: number;
+  limit?: number;
+  skipHook?: boolean;
+  subQueries?: SubQuery[];
+}
+
+export interface FindExistsOptions {
+  where?: FindOptionsWhere;
+  relations?: FindOptionsRelations;
+}
+
+export interface FindCountOptions {
+  where?: FindOptionsWhere;
+  relations?: FindOptionsRelations;
+  order?: FindOptionsOrder;
+  offset?: number;
+}

package/src/storage/GroupOptionTypes.ts

@@ -0,0 +1,32 @@
+import type { FindOptionsWhere } from './FindOptionsTypes';
+
+// Add these types at the top of the file
+export interface GroupByOptions {
+  where?: FindOptionsWhere;
+  groupBy?: string[];
+  dateRange?: {
+    start: string;
+    end: string;
+  };
+  dateGrouping?: 'month' | 'day';
+  limit?: number;
+  offset?: number;
+}
+
+export interface GroupResult {
+  group: Record<string, string | number>;
+  count: number;
+  entityIds: string[];
+}
+
+export interface GroupByResponse {
+  results: GroupResult[];
+  meta: {
+    totalCount: number;
+    dateRange?: {
+      start: string;
+      end: string;
+    };
+    groupings: string[];
+  };
+}

package/src/storage/operator/And.ts

@@ -0,0 +1,10 @@
+import type { ValueObject } from 'jsonld';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function And<T extends number | Date | string | boolean | ValueObject>(value: T[]): FindOperator<T[], 'and'> {
+  return new FindOperator({
+    operator: 'and',
+    value
+  });
+}

package/src/storage/operator/Contains.ts

@@ -0,0 +1,9 @@
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Contains(value: string): FindOperator<string, 'contains'> {
+  return new FindOperator({
+    operator: 'contains',
+    value
+  });
+}

package/src/storage/operator/Equal.ts

@@ -0,0 +1,13 @@
+import type { ValueObject } from 'jsonld';
+import type { OrArray } from '../../util/Types';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Equal<T extends OrArray<number | Date | string | boolean | ValueObject>>(
+  value: T
+): FindOperator<T, 'equal'> {
+  return new FindOperator({
+    operator: 'equal',
+    value
+  });
+}

package/src/storage/operator/Exists.ts

@@ -0,0 +1,6 @@
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Exists(): FindOperator<undefined, 'exists'> {
+  return new FindOperator({ operator: 'exists' });
+}

package/src/storage/operator/GreaterThan.ts

@@ -0,0 +1,12 @@
+import type { ValueObject } from 'jsonld';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function GreaterThan<T extends number | Date | string | ValueObject>(
+  value: T
+): FindOperator<T, 'gt'> {
+  return new FindOperator({
+    operator: 'gt',
+    value
+  });
+}

package/src/storage/operator/GreaterThanOrEqual.ts

@@ -0,0 +1,12 @@
+import type { ValueObject } from 'jsonld';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function GreaterThanOrEqual<T extends number | Date | string | ValueObject>(
+  value: T
+): FindOperator<T, 'gte'> {
+  return new FindOperator({
+    operator: 'gte',
+    value
+  });
+}

package/src/storage/operator/In.ts

@@ -0,0 +1,12 @@
+import type { ValueObject } from 'jsonld';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function In<T extends number | Date | string | boolean | ValueObject>(
+  value: T[]
+): FindOperator<T[], 'in'> {
+  return new FindOperator({
+    operator: 'in',
+    value
+  });
+}

package/src/storage/operator/Inverse.ts

@@ -0,0 +1,11 @@
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Inverse<T>(
+  value: T | FindOperator<T, any>
+): FindOperator<T, 'inverse'> {
+  return new FindOperator({
+    operator: 'inverse',
+    value
+  });
+}

package/src/storage/operator/InversePath.ts

@@ -0,0 +1,17 @@
+import { FindOperator } from '../FindOperator';
+
+export interface InversePathValue<T> {
+  subPath: string | FindOperator<any, 'sequencePath' | 'zeroOrMorePath' | 'oneOrMorePath'>;
+  value?: T | FindOperator<T, any>;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function InversePath<
+  T,
+  TI extends InversePathValue<T>
+>(value: TI): FindOperator<TI, 'inversePath'> {
+  return new FindOperator({
+    operator: 'inversePath',
+    value
+  });
+}

package/src/storage/operator/InverseRelation.ts

@@ -0,0 +1,18 @@
+import { FindOperator } from '../FindOperator';
+import type { FindOptionsRelations } from '../FindOptionsTypes';
+
+export interface InverseRelationOperatorValue {
+  resolvedName: string;
+  relations?: FindOptionsRelations;
+  [key: string]: any;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function InverseRelation(
+  value: InverseRelationOperatorValue
+): FindOperator<InverseRelationOperatorValue, 'inverseRelation'> {
+  return new FindOperator({
+    operator: 'inverseRelation',
+    value
+  });
+}

package/src/storage/operator/InverseRelationOrder.ts

@@ -0,0 +1,17 @@
+import { FindOperator } from '../FindOperator';
+import type { FindOptionsOrder, FindOptionsWhere } from '../FindOptionsTypes';
+
+export interface InverseRelationOrderValue {
+  order: FindOptionsOrder;
+  where?: FindOptionsWhere;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function InverseRelationOrder(
+  value: InverseRelationOrderValue
+): FindOperator<InverseRelationOrderValue, 'inverseRelationOrder'> {
+  return new FindOperator({
+    operator: 'inverseRelationOrder',
+    value
+  });
+}

package/src/storage/operator/LessThan.ts

@@ -0,0 +1,12 @@
+import type { ValueObject } from 'jsonld';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function LessThan<T extends number | Date | string | ValueObject>(
+  value: T
+): FindOperator<T, 'lt'> {
+  return new FindOperator({
+    operator: 'lt',
+    value
+  });
+}

package/src/storage/operator/LessThanOrEqual.ts

@@ -0,0 +1,12 @@
+import type { ValueObject } from 'jsonld';
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function LessThanOrEqual<T extends number | Date | string | ValueObject>(
+  value: T
+): FindOperator<T, 'lte'> {
+  return new FindOperator({
+    operator: 'lte',
+    value
+  });
+}

package/src/storage/operator/Not.ts

@@ -0,0 +1,11 @@
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Not<T>(
+  value: T | FindOperator<T, any>
+): FindOperator<T, 'not'> {
+  return new FindOperator({
+    operator: 'not',
+    value
+  });
+}

package/src/storage/operator/OneOrMorePath.ts

@@ -0,0 +1,17 @@
+import { FindOperator } from '../FindOperator';
+
+export interface OneOrMorePathValue<T> {
+  subPath: string | FindOperator<any, 'sequencePath' | 'inversePath'>;
+  value?: string | FindOperator<T, any>;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function OneOrMorePath<
+  T,
+  TI extends OneOrMorePathValue<T>
+>(value: TI): FindOperator<TI, 'oneOrMorePath'> {
+  return new FindOperator({
+    operator: 'oneOrMorePath',
+    value
+  });
+}

package/src/storage/operator/Sequence.ts

@@ -0,0 +1,11 @@
+import { FindOperator } from '../FindOperator';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Sequence<T>(
+  value: T | FindOperator<T, any>
+): FindOperator<T, 'sequence'> {
+  return new FindOperator({
+    operator: 'sequence',
+    value
+  });
+}

package/src/storage/operator/SequencePath.ts

@@ -0,0 +1,17 @@
+import { FindOperator } from '../FindOperator';
+
+export interface SequencePathValue<T> {
+  subPath: (string | FindOperator<any, 'zeroOrMorePath' | 'inversePath' | 'oneOrMorePath'>)[];
+  value?: string | FindOperator<T, any>;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function SequencePath<
+  T,
+  TI extends SequencePathValue<T>
+>(value: TI): FindOperator<TI, 'sequencePath'> {
+  return new FindOperator({
+    operator: 'sequencePath',
+    value
+  });
+}

package/src/storage/operator/ZeroOrMorePath.ts

@@ -0,0 +1,17 @@
+import { FindOperator } from '../FindOperator';
+
+export interface ZeroOrMorePathValue<T> {
+  subPath: string | FindOperator<any, 'sequencePath' | 'inversePath'>;
+  value?: string | FindOperator<T, any>;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function ZeroOrMorePath<
+  T,
+  TI extends ZeroOrMorePathValue<T>
+>(value: TI): FindOperator<TI, 'zeroOrMorePath'> {
+  return new FindOperator({
+    operator: 'zeroOrMorePath',
+    value
+  });
+}