@comake/skl-js-engine/src/util/Types.ts

Standard Knowledge Language Javascript Engine

/* 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>>;
}