@comake/skl-js-engine 1.3.8 → 1.3.10

package/src/util/Types.ts

@@ -0,0 +1,399 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import type { ReferenceNodeObject, TriplesMap } from '@comake/rmlmapper-js';
+import type {
+  GraphObject,
+  IdMap,
+  IncludedBlock,
+  IndexMap,
+  LanguageMap,
+  ListObject,
+  NodeObject,
+  SetObject,
+  TypeMap
+} from 'jsonld';
+import type { Frame } from 'jsonld/jsonld-spec';
+import type { EngineConstants } from '../constants';
+import type { FindAllOptions, FindOneOptions, FindOptionsWhere } from '../storage/FindOptionsTypes';
+import type { GroupByOptions, GroupByResponse } from '../storage/GroupOptionTypes';
+import type { RawQueryResult } from '../storage/query-adapter/QueryAdapter';
+import type { RDF, SHACL } from './Vocabularies';
+
+export type JSONPrimitive = string | number | boolean | null;
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+export interface JSONObject {
+  [key: string]: JSONValue | undefined;
+}
+export interface JSONArray extends Array<JSONValue> {}
+
+export type JSONValue = JSONPrimitive | JSONObject | JSONValue[];
+
+export interface RdfList<T> {
+  [RDF.first]: T;
+  [RDF.rest]?: RdfList<T> | typeof RDF.nil | ReferenceNodeObject;
+}
+
+export interface ValueObject<T extends string | boolean | number | JSONObject | JSONArray> {
+  ['@type']: string;
+  ['@value']: T;
+  ['@language']?: string;
+  ['@direction']?: string;
+}
+
+export type IRIObject<T extends string = string> = { '@id': T };
+
+export type ShaclIRI = string | IRIObject;
+export type ShaclIRIOrLiteral = ShaclIRI | ValueObject<any>;
+
+export type NodeKindValues =
+  | typeof SHACL.Literal
+  | typeof SHACL.IRI
+  | typeof SHACL.BlankNode
+  | typeof SHACL.BlankNodeOrIRI
+  | typeof SHACL.BlankNodeOrLiteral
+  | typeof SHACL.IRIOrLiteral;
+
+export type BaseShape = NodeObject & {
+  [SHACL.targetNode]?: ShaclIRIOrLiteral;
+  [SHACL.targetClass]?: ShaclIRI;
+  [SHACL.targetSubjectsOf]?: ShaclIRI;
+  [SHACL.targetObjectOf]?: ShaclIRI;
+  [SHACL.severity]?: ShaclIRI;
+  [SHACL.message]?: OrArray<ValueObject<string>>;
+  [SHACL.deactivated]?: ValueObject<boolean>;
+  [SHACL.and]?: ShapesListShape;
+  [SHACL.class]?: OrArray<ShaclIRI>;
+  [SHACL.closed]?: ValueObject<boolean>;
+  [SHACL.ignoredProperties]?: ShaclIRI[];
+  [SHACL.disjoint]?: OrArray<ShaclIRI>;
+  [SHACL.equals]?: OrArray<ShaclIRI>;
+  [SHACL.in]?: ListObject;
+  [SHACL.languageIn]?: string[];
+  [SHACL.maxExclusive]?: ValueObject<number>;
+  [SHACL.maxInclusive]?: ValueObject<number>;
+  [SHACL.maxLength]?: ValueObject<number>;
+  [SHACL.minExclusive]?: ValueObject<number>;
+  [SHACL.minInclusive]?: ValueObject<number>;
+  [SHACL.minLength]?: ValueObject<number>;
+  [SHACL.nodeKind]?: IRIObject<NodeKindValues>;
+  [SHACL.or]?: ShapesListShape;
+  [SHACL.pattern]?: ValueObject<string>;
+  [SHACL.flags]?: ValueObject<string>;
+  [SHACL.xone]?: ShapesListShape;
+};
+
+export type ShapesListShape = (PropertyShape | NodeShape)[];
+
+export interface PropertyShape extends BaseShape {
+  [SHACL.path]: PathTypes;
+  [SHACL.datatype]?: ShaclIRI;
+  [SHACL.node]?: OrArray<NodeShape>;
+  [SHACL.name]?: ValueObject<string>;
+  [SHACL.description]?: ValueObject<string>;
+  [SHACL.minCount]?: ValueObject<number>;
+  [SHACL.maxCount]?: ValueObject<number>;
+  [SHACL.lessThanOrEquals]?: OrArray<ShaclIRI>;
+  [SHACL.lessThan]?: OrArray<ShaclIRI>;
+  [SHACL.qualifiedValueShape]?: OrArray<BaseShape>;
+  [SHACL.qualifiedMaxCount]?: ValueObject<number>;
+  [SHACL.qualifiedMinCount]?: ValueObject<number>;
+  [SHACL.qualifiedValueShapesDisjoint]?: ValueObject<boolean>;
+  [SHACL.uniqueLang]?: ValueObject<boolean>;
+}
+
+export interface NodeShape extends BaseShape {
+  '@type': typeof SHACL.NodeShape;
+  [EngineConstants.prop.label]?: ValueObject<string>;
+  [SHACL.property]: OrArray<PropertyShape>;
+}
+
+export interface InverseShaclPath extends NodeObject {
+  [SHACL.inversePath]: PathShape;
+}
+
+export interface ZeroOrMoreShaclPath extends NodeObject {
+  [SHACL.zeroOrMorePath]: PathShape;
+}
+
+export interface OneOrMoreShaclPath extends NodeObject {
+  [SHACL.oneOrMorePath]: PathShape;
+}
+
+export interface ZeroOrOneShaclPath extends NodeObject {
+  [SHACL.zeroOrOnePath]: PathShape;
+}
+
+export interface AlternativeShaclPath extends NodeObject {
+  [SHACL.alternativePath]: PathTypes[];
+}
+
+export type PathTypes =
+  | ShaclIRI
+  | AlternativeShaclPath
+  | ZeroOrMoreShaclPath
+  | OneOrMoreShaclPath
+  | ZeroOrOneShaclPath
+  | InverseShaclPath;
+
+export type PathShape = OrArray<PathTypes>;
+
+export type Mapping = NodeObject & {
+  [EngineConstants.prop.preProcessingMapping]?: OrArray<TriplesMap>;
+  [EngineConstants.prop.preProcessingMappingFrame]?: ValueObject<JSONObject>;
+  [EngineConstants.prop.inputsMapping]?: OrArray<TriplesMap>;
+  [EngineConstants.prop.inputsMappingFrame]?: ValueObject<JSONObject>;
+  [EngineConstants.prop.inputsMappingRef]?: string | ValueObject<string>;
+  [EngineConstants.prop.operationId]?: ValueObject<string>;
+  [EngineConstants.prop.operationMapping]?: TriplesMap;
+  [EngineConstants.prop.capability]?: ReferenceNodeObject;
+  [EngineConstants.prop.outputsMapping]?: OrArray<TriplesMap>;
+  [EngineConstants.prop.outputsMappingFrame]?: ValueObject<JSONObject>;
+  [EngineConstants.prop.series]?: { '@list': CapabilityMapping[] } | (RdfList<CapabilityMapping> & NodeObject);
+  [EngineConstants.prop.parallel]?: OrArray<CapabilityMapping>;
+};
+
+export type Capability = NodeObject & {
+  '@id': string;
+  '@type': typeof EngineConstants.spec.capability;
+  [EngineConstants.prop.label]?: ValueObject<string>;
+  [EngineConstants.prop.inputsContext]?: ValueObject<JSONObject>;
+  [EngineConstants.prop.inputs]?: NodeShape | ReferenceNodeObject;
+  [EngineConstants.prop.outputsContext]?: ValueObject<JSONObject>;
+  [EngineConstants.prop.outputs]?: NodeShape | ReferenceNodeObject;
+};
+
+export type CapabilityMapping = Mapping & {
+  [EngineConstants.prop.capability]: ReferenceNodeObject;
+  [EngineConstants.prop.object]?: ReferenceNodeObject;
+  [EngineConstants.prop.integration]?: ReferenceNodeObject;
+};
+
+export type MappingWithInputs = CapabilityMapping &
+Required<Pick<CapabilityMapping, typeof EngineConstants.prop.inputs | typeof EngineConstants.prop.inputsMapping>>;
+
+export type MappingWithInputsReference = CapabilityMapping &
+Required<Pick<CapabilityMapping, typeof EngineConstants.prop.inputsReference>>;
+
+export type MappingWithOutputsMapping = CapabilityMapping &
+Required<
+Pick<
+CapabilityMapping,
+      typeof EngineConstants.prop.outputsMapping | typeof EngineConstants.prop.outputsMappingFrame
+>
+>;
+
+export type MappingWithSeries = CapabilityMapping &
+Required<Pick<CapabilityMapping, typeof EngineConstants.prop.series>>;
+
+export type MappingWithParallel = CapabilityMapping &
+Required<Pick<CapabilityMapping, typeof EngineConstants.prop.parallel>>;
+
+export interface SeriesCapabilityArgs extends JSONObject {
+  originalCapabilityParameters: JSONObject;
+  previousCapabilityReturnValue: JSONObject;
+  allStepsResults: JSONObject[];
+}
+
+export type TriggerMapping = Mapping & {
+  [EngineConstants.prop.integration]: ReferenceNodeObject;
+};
+
+export type PossibleArrayFieldValues =
+  | boolean
+  | number
+  | string
+  | NodeObject
+  | GraphObject
+  | ValueObject<any>
+  | ListObject
+  | SetObject;
+
+export type EntityFieldSingularValue =
+  | boolean
+  | number
+  | string
+  | NodeObject
+  | GraphObject
+  | ValueObject<any>
+  | ListObject
+  | SetObject;
+
+export type EntityFieldValue =
+  | OrArray<EntityFieldSingularValue>
+  | LanguageMap
+  | IndexMap
+  | IncludedBlock
+  | IdMap
+  | TypeMap
+  | NodeObject[keyof NodeObject];
+
+export interface Entity {
+  '@id': string;
+  '@type': OrArray<string>;
+  [key: string]: EntityFieldValue;
+}
+
+export type OrArray<T> = T | T[];
+
+export interface OperationResponse extends JSONObject {
+  data: JSONObject;
+  operationParameters: JSONObject;
+}
+
+export interface CapabilityConfig {
+  /**
+   * Callbacks to execute upon events.
+   * If global callbacks are provided, both are executed.
+   */
+  callbacks?: Callbacks;
+  /**
+   * When true, disables validation of capability parameters and
+   * return values according to schemas. Overrides the global setting.
+   */
+  readonly disableValidation?: boolean;
+  /**
+   * An object containing files keyed on their title that can be used in mappings.
+   * Merged with the global setting. The capability config taking prededence in the case of overlapping names.
+   */
+  readonly inputFiles?: Record<string, string>;
+  /**
+   * Manually defined functions which can be used in mappings.
+   * Merged with the global setting. The capability config taking prededence in the case of overlapping names.
+   */
+  readonly functions?: Record<string, (args: any | any[]) => any>;
+
+  /**
+   * When true, the operation will be streamed.
+   */
+  readonly stream?: boolean;
+
+  /**
+   * When true, the operation will be buffered.
+   */
+  readonly buffer?: boolean;
+}
+
+export interface Callbacks {
+  /**
+   * Callback run when a Capability starts being executed
+   */
+  onCapabilityStart?: (capability: string, args: Record<string, any>) => void;
+  /**
+   * Callback run when a Capability is finished being executed
+   */
+  onCapabilityEnd?: (capability: string, returnValue: Record<string, any>) => void;
+}
+
+export interface SKLEngineInterface {
+  /**
+   * Finds the first entity by the given find options
+   */
+  find: (options?: FindOneOptions) => Promise<Entity>;
+
+  /**
+   * Finds the first entity that matches the given where condition
+   */
+  findBy: (where: FindOptionsWhere, notFoundErrorMessage?: string) => Promise<Entity>;
+
+  /**
+   * Finds the first entity that matches the given where condition, or undefined if not found
+   */
+  findByIfExists: (options: FindOptionsWhere) => Promise<Entity | undefined>;
+
+  /**
+   * Finds entities that match the given find options
+   */
+  findAll: (options?: FindAllOptions) => Promise<Entity[]>;
+
+  /**
+   * Groups entities by the given options
+   */
+  groupBy: (options: GroupByOptions) => Promise<GroupByResponse>;
+
+  /**
+   * Finds entities that match the given where condition
+   */
+  findAllBy: (where: FindOptionsWhere) => Promise<Entity[]>;
+
+  /**
+   * Determines if an entity matching the given options exists
+   */
+  exists: (options?: FindAllOptions) => Promise<boolean>;
+
+  /**
+   * Returns a count of entities matching the given options
+   */
+  count: (options?: FindAllOptions) => Promise<number>;
+
+  /**
+   * Saves a given entity or entities
+   */
+  save: ((entity: Entity) => Promise<Entity>) & ((entities: Entity[]) => Promise<Entity[]>);
+
+  /**
+   * Updates an entity or entities partially
+   */
+  update: ((id: string, attributes: Partial<Entity>) => Promise<void>) &
+  ((ids: string[], attributes: Partial<Entity>) => Promise<void>);
+
+  /**
+   * Removes an entity or entities from the database by id
+   */
+  delete: ((id: string) => Promise<void>) & ((ids: string[]) => Promise<void>);
+
+  /**
+   * Removes a given entity or entities from the database
+   */
+  destroy: ((entity: Entity) => Promise<Entity>) & ((entities: Entity[]) => Promise<Entity[]>);
+
+  /**
+   * Performs a mapping operation
+   */
+  performMapping: (
+    args: JSONValue,
+    mapping: OrArray<NodeObject>,
+    frame?: Record<string, any>,
+    capabilityConfig?: CapabilityConfig,
+  ) => Promise<NodeObject>;
+
+  /**
+   * Executes a raw query
+   */
+  executeRawQuery: <T extends RawQueryResult>(query: string) => Promise<T[]>;
+
+  /**
+   * Executes a raw update query
+   */
+  executeRawUpdate: (query: string) => Promise<void>;
+
+  /**
+   * Executes a raw construct query
+   */
+  executeRawConstructQuery: (query: string, frame?: Frame) => Promise<GraphObject>;
+
+  /**
+   * Record of capability handlers by name
+   */
+  capability: Record<string, (params: JSONObject, capabilityConfig?: CapabilityConfig) => Promise<any>>;
+
+  /**
+   * Finds and executes a capability
+   */
+  findAndExecuteCapability: (
+    capabilityId: string,
+    args: JSONObject,
+    capabilityConfig?: CapabilityConfig,
+  ) => Promise<OrArray<NodeObject>>;
+
+  executeCapability: (
+    capability: Capability,
+    capabilityArgs: JSONObject,
+    capabilityConfig?: CapabilityConfig,
+  ) => Promise<OrArray<NodeObject>>;
+
+  executeMapping: (
+    mapping: Mapping,
+    args: JSONObject,
+    capabilityConfig?: CapabilityConfig,
+    account?: Entity,
+  ) => Promise<OrArray<NodeObject>>;
+}

package/src/util/Util.ts

@@ -0,0 +1,116 @@
+import type { ReferenceNodeObject } from '@comake/rmlmapper-js';
+import { getIdFromNodeObjectIfDefined } from '@comake/rmlmapper-js';
+import * as jsonld from 'jsonld';
+import type { NodeObject, ValueObject } from 'jsonld';
+import { Parser, Store } from 'n3';
+import type { EntityFieldSingularValue, EntityFieldValue, JSONObject, RdfList } from './Types';
+import { RDF, XSD } from './Vocabularies';
+
+export async function convertJsonLdToQuads(jsonldDoc: any): Promise<Store> {
+  const nquads = (await jsonld.toRDF(jsonldDoc, { format: 'application/n-quads' })) as unknown as string;
+  const turtleParser = new Parser({ format: 'application/n-quads' });
+  const store = new Store();
+  turtleParser.parse(nquads).forEach((quad): void => {
+    store.addQuad(quad);
+  });
+  return store;
+}
+
+export function toJSON(jsonLd: NodeObject, convertBeyondFirstLevel = true): JSONObject {
+  [ '@context', '@id', '@type' ].forEach((key): void => {
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    delete jsonLd[key];
+  });
+  if (convertBeyondFirstLevel) {
+    Object.keys(jsonLd).forEach((key): void => {
+      if (Array.isArray(jsonLd[key])) {
+        (jsonLd[key] as any[])!.forEach((item, index): void => {
+          if (typeof item === 'object') {
+            (jsonLd[key] as any[])[index] = toJSON(item);
+          }
+        });
+      } else if (typeof jsonLd[key] === 'object') {
+        jsonLd[key] = toJSON(jsonLd[key] as NodeObject);
+      }
+    });
+  }
+  return jsonLd as JSONObject;
+}
+
+export function ensureArray<T>(arrayable: T | T[]): T[] {
+  if (arrayable !== null && arrayable !== undefined) {
+    return Array.isArray(arrayable) ? arrayable : [ arrayable ];
+  }
+  return [];
+}
+
+export function getValueIfDefined<T>(fieldValue?: EntityFieldValue): T | undefined {
+  if (fieldValue && Array.isArray(fieldValue)) {
+    return fieldValue.map(
+      (valueItem): EntityFieldSingularValue => getValueIfDefined<EntityFieldSingularValue>(valueItem)!
+    ) as unknown as T;
+  }
+  if (fieldValue && typeof fieldValue === 'object') {
+    return (fieldValue as ValueObject)['@value'] as unknown as T;
+  }
+  if (fieldValue !== undefined && fieldValue !== null) {
+    return fieldValue as unknown as T;
+  }
+}
+
+export function isUrl(value: any): boolean {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  try {
+    // eslint-disable-next-line no-new
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function rdfListToArray<T extends NodeObject>(list: { '@list': T[] } | RdfList<T>): T[] {
+  if (!('@list' in list)) {
+    return [
+      list[RDF.first],
+      ...getIdFromNodeObjectIfDefined(list[RDF.rest] as ReferenceNodeObject) === RDF.nil
+        ? []
+        : rdfListToArray(list[RDF.rest] as RdfList<T>)
+    ];
+  }
+  return list['@list'];
+}
+
+export function parseJSONOrDefault<T>(json: string, defaultValue: T): T {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return defaultValue;
+  }
+}
+
+export const dataTypeMapping = {
+  string: XSD.string,
+  boolean: XSD.boolean,
+  integer: XSD.integer,
+  float: XSD.float,
+  double: XSD.double,
+  dateTime: XSD.dateTime,
+  json: RDF.JSON
+};
+
+export function getEntityValue<T>(
+  value: T,
+  dataType: keyof typeof dataTypeMapping = 'string'
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+): { '@type': string; '@value': T } {
+  return {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '@type': dataTypeMapping[dataType],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '@value': value
+  };
+}

package/src/util/Vocabularies/Shared.ts

@@ -0,0 +1,99 @@
+import { createNamespace } from './helper';
+
+export const XSD_NAMESPACE = 'http://www.w3.org/2001/XMLSchema#';
+export const RDF_NAMESPACE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+export const RDFS_NAMESPACE = 'http://www.w3.org/2000/01/rdf-schema#';
+export const R2RML_NAMESPACE = 'http://www.w3.org/ns/r2rml#';
+export const OWL_NAMESPACE = 'https://www.w3.org/2002/07/owl#';
+export const SHACL_NAMESPACE = 'http://www.w3.org/ns/shacl#';
+
+export const RDF = createNamespace(RDF_NAMESPACE, [ 'Property', 'type', 'datatype', 'JSON', 'first', 'rest', 'nil' ]);
+
+export const RDFS = createNamespace(RDFS_NAMESPACE, [ 'subClassOf', 'label', 'range', 'domain' ]);
+
+export const R2RML = createNamespace(R2RML_NAMESPACE, [ 'TriplesMap' ]);
+
+export const XSD = createNamespace(XSD_NAMESPACE, [
+  'boolean',
+  'integer',
+  'double',
+  'decimal',
+  'string',
+  'float',
+  'positiveInteger',
+  'negativeInteger',
+  'int',
+  'date',
+  'time',
+  'dateTime',
+  'label'
+]);
+
+export const OWL = createNamespace(OWL_NAMESPACE, [
+  'Restriction',
+  'onProperty',
+  'allValuesFrom',
+  'Class',
+  'intersectionOf',
+  'someValuesFrom',
+  'ObjectProperty'
+]);
+
+export const SHACL = createNamespace(SHACL_NAMESPACE, [
+  'NodeShape',
+  'PropertyShape',
+  'Literal',
+  'IRI',
+  'BlankNode',
+  'BlankNodeOrIRI',
+  'BlankNodeOrLiteral',
+  'IRIOrLiteral',
+  'property',
+  'path',
+  'name',
+  'description',
+  'minCount',
+  'maxCount',
+  'targetNode',
+  'targetClass',
+  'targetSubjectsOf',
+  'targetObjectOf',
+  'severity',
+  'message',
+  'deactivated',
+  'and',
+  'or',
+  'class',
+  'closed',
+  'ignoredProperties',
+  'datatype',
+  'disjoint',
+  'equals',
+  'in',
+  'languageIn',
+  'lessThan',
+  'lessThanOrEquals',
+  'maxCount',
+  'maxExclusive',
+  'maxInclusive',
+  'maxLength',
+  'minCount',
+  'minExclusive',
+  'minInclusive',
+  'minLength',
+  'nodeKind',
+  'pattern',
+  'flags',
+  'qualifiedMaxCount',
+  'qualifiedMinCount',
+  'qualifiedValueShape',
+  'qualifiedValueShapesDisjoint',
+  'uniqueLang',
+  'xone',
+  'inversePath',
+  'zeroOrMorePath',
+  'oneOrMorePath',
+  'zeroOrOnePath',
+  'alternativePath',
+  'node'
+]);

package/src/util/Vocabularies/helper.ts

@@ -0,0 +1,14 @@
+export type Namespace<T extends string, TBase extends string> = {
+  [key in T]: `${TBase}${key}`;
+};
+
+export function createNamespace<T extends string, TBase extends string>(
+  baseUri: TBase,
+  localNames: T[]
+): Namespace<T, TBase> {
+  return localNames.reduce(
+    (obj: Namespace<T, TBase>, localName): Namespace<T, TBase> => ({ ...obj, [localName]: `${baseUri}${localName}` }),
+    // eslint-disable-next-line @typescript-eslint/prefer-reduce-type-parameter
+    {} as Namespace<T, TBase>
+  );
+}