@comake/skl-js-engine 1.3.9 → 1.3.10

package/src/SklEngineOptions.ts

@@ -0,0 +1,28 @@
+import type { SparqlQueryAdapterOptions } from './storage/query-adapter/sparql/SparqlQueryAdapterOptions';
+import type { Callbacks } from './util/Types';
+
+export type SklEngineOptions = SparqlQueryAdapterOptions & {
+  /**
+   * Callbacks to execute upon events.
+   */
+  readonly callbacks?: Callbacks;
+  /**
+   * Manually defined functions which can be used in mappings.
+   */
+  readonly functions?: Record<string, (args: any | any[]) => any>;
+  /**
+   * When true, disables validation of verb parameters and return values according to schemas
+   */
+  readonly disableValidation?: boolean;
+  /**
+   * An object containing files keyed on their title that can be used in mappings.
+   */
+  readonly inputFiles?: Record<string, string>;
+
+  readonly debugMode?: boolean;
+
+  /**
+   * The path to the executor script.
+   */
+  readonly scriptPath?: string;
+};

package/src/constants.ts

@@ -0,0 +1,120 @@
+import {
+  SKL_DATA_NAMESPACE as SKL_DATA_NAMESPACE_VOCAB,
+  SKL_ENGINE,
+  SKL_ENGINE_NAMESPACE as SKL_ENGINE_NAMESPACE_VOCAB,
+  SKL_NAMESPACE as SKL_NAMESPACE_VOCAB,
+  SKL_PROPERTY,
+  SKL_SPECS
+} from './util/Vocabularies';
+import {
+  OWL as OWL_VOCAB,
+  R2RML as R2RML_VOCAB,
+  RDF as RDF_VOCAB,
+  RDFS as RDFS_VOCAB, SHACL as SHACL_VOCAB, SHACL_NAMESPACE as SHACL_NAMESPACE_VOCAB, XSD as XSD_VOCAB
+} from './util/Vocabularies/Shared';
+
+export const SKL_NAMESPACE = SKL_NAMESPACE_VOCAB;
+export const SKL_DATA_NAMESPACE = SKL_DATA_NAMESPACE_VOCAB;
+export const SKL_ENGINE_NAMESPACE = SKL_ENGINE_NAMESPACE_VOCAB;
+
+export const OWL = OWL_VOCAB;
+export const RDF = RDF_VOCAB;
+export const RDFS = RDFS_VOCAB;
+export const R2RML = R2RML_VOCAB;
+export const XSD = XSD_VOCAB;
+export const SHACL = SHACL_VOCAB;
+export const SHACL_NAMESPACE = SHACL_NAMESPACE_VOCAB;
+export const PROP_ENTITY_ID = '@id';
+export const PROP_ENTITY_TYPE = '@type';
+export const PROP_ENTITY_VALUE = '@value';
+
+// RML constants
+
+export const RML_LIST = '@list';
+
+export const OPEN_API_RUNTIME_AUTHORIZATION = 'getOpenApiRuntimeAuthorization';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const EngineConstants = {
+  spec: {
+    capability: SKL_SPECS.Capability,
+    capabilityMapping: SKL_SPECS.CapabilityMapping,
+    triggerCapabilityMapping: SKL_SPECS.TriggerCapabilityMapping,
+    invalidTokenErrorMatcher: SKL_SPECS['integration/InvalidTokenErrorMatcher'],
+    jsonDataSource: SKL_SPECS.JsonDataSource,
+    mapping: SKL_SPECS.Mapping,
+    inputs: SKL_SPECS.Inputs,
+    openApi: SKL_SPECS.OpenAPI,
+    codeBlock: SKL_SPECS.CodeBlock,
+    integrationAuthenticationCredential: SKL_SPECS['integration/AuthenticationCredential'],
+    integrationInterface: SKL_SPECS['integration/IntegrationInterface']
+  },
+  prop: {
+    capability: SKL_PROPERTY.capability,
+    inputs: SKL_PROPERTY.inputs,
+    outputs: SKL_PROPERTY.outputs,
+    inputsContext: SKL_PROPERTY.inputsContext,
+    outputsContext: SKL_PROPERTY.outputsContext,
+    invalidTokenErrorMatcher: SKL_PROPERTY['integration/invalidTokenErrorMatcher'],
+    invalidTokenErrorMatcherStatus: SKL_PROPERTY['integration/invalidTokenErrorMatcherStatus'],
+    invalidTokenErrorMatcherMessageRegex: SKL_PROPERTY['integration/invalidTokenErrorMatcherMessageRegex'],
+    refreshToken: SKL_PROPERTY['integration/credential/refreshToken'],
+    jwtBearerOptions: SKL_PROPERTY['integration/credential/jwtBearerOptions'],
+    accessToken: SKL_PROPERTY['integration/credential/accessToken'],
+    bearerToken: SKL_PROPERTY['integration/credential/bearerToken'],
+    username: SKL_PROPERTY['integration/username'],
+    password: SKL_PROPERTY['integration/password'],
+    oneTimePassword: SKL_PROPERTY['integration/oneTimePassword'],
+    apiKey: SKL_PROPERTY['integration/apiKey'],
+    declarativeApiDescription: SKL_PROPERTY['integration/declarativeApiDescription'],
+    overrideBasePath: SKL_PROPERTY['integration/overrideBasePath'],
+    schemeName: SKL_PROPERTY['integration/schemeName'],
+    oauthFlow: SKL_PROPERTY['integration/oauthFlow'],
+    stage: SKL_PROPERTY['integration/stage'],
+    operationId: SKL_PROPERTY.operationId,
+
+    data: SKL_PROPERTY.data,
+    source: SKL_PROPERTY.source,
+    headers: SKL_PROPERTY.headers,
+    object: SKL_PROPERTY.object,
+    dataSource: SKL_PROPERTY.dataSource,
+
+    series: SKL_PROPERTY['mapping/series'],
+    parallel: SKL_PROPERTY['mapping/parallel'],
+    inputsReference: SKL_PROPERTY['mapping/inputsReference'],
+    inputsMapping: SKL_PROPERTY['mapping/inputsMapping'],
+    inputsMappingFrame: SKL_PROPERTY['mapping/inputsMappingFrame'],
+    inputsMappingRef: SKL_PROPERTY['mapping/inputsMappingRef'],
+    inputsMappingFrameRef: SKL_PROPERTY['mapping/inputsMappingFrameRef'],
+    outputsMapping: SKL_PROPERTY['mapping/outputsMapping'],
+    outputsMappingFrame: SKL_PROPERTY['mapping/outputsMappingFrame'],
+    preProcessingMapping: SKL_PROPERTY['mapping/preProcessingMapping'],
+    preProcessingMappingFrame: SKL_PROPERTY['mapping/preProcessingMappingFrame'],
+    operationMapping: SKL_PROPERTY['mapping/operationMapping'],
+
+    type: SKL_PROPERTY.type,
+    dateCreated: SKL_PROPERTY.dateTimeCreated,
+    dateModified: SKL_PROPERTY.dateTimeModified,
+    label: SKL_PROPERTY.label,
+    identifier: SKL_PROPERTY.identifier,
+    codeBody: SKL_PROPERTY['content/codeBody'],
+    codeBlocks: SKL_PROPERTY['content/codeBlocks'],
+    integration: SKL_PROPERTY['integration/integration'],
+    accountOrUser: SKL_PROPERTY.accountOrUser,
+
+    capabilityType: SKL_PROPERTY.capabilityType
+  },
+  dataSource: {
+    update: SKL_ENGINE.update,
+    findAll: SKL_ENGINE.findAll,
+    findAllBy: SKL_ENGINE.findAllBy,
+    find: SKL_ENGINE.find,
+    findBy: SKL_ENGINE.findBy,
+    exists: SKL_ENGINE.exists,
+    existsResult: SKL_ENGINE.existsResult,
+    count: SKL_ENGINE.count,
+    countResult: SKL_ENGINE.countResult,
+    save: SKL_ENGINE.save,
+    destroy: SKL_ENGINE.destroy
+  }
+};

package/src/customCapabilities.ts

@@ -0,0 +1,65 @@
+import type { NodeObject } from 'jsonld';
+import type { CapabilityConfig, JSONObject, OrArray } from './util/Types';
+
+// Define the custom capability handler type
+// Using any to avoid circular dependency
+export type CustomCapabilityHandler = (
+  args: JSONObject,
+  sklEngine: any,
+  capabilityConfig?: CapabilityConfig
+) => Promise<OrArray<NodeObject>>;
+
+// Global custom capabilities registry
+class GlobalCustomCapabilitiesRegistry {
+  private readonly customCapabilities: Map<string, CustomCapabilityHandler> = new Map();
+
+  public register(capabilityId: string, handler: CustomCapabilityHandler): void {
+    this.customCapabilities.set(capabilityId, handler);
+  }
+
+  public unregister(capabilityId: string): boolean {
+    return this.customCapabilities.delete(capabilityId);
+  }
+
+  public has(capabilityId: string): boolean {
+    return this.customCapabilities.has(capabilityId);
+  }
+
+  public async execute(
+    capabilityId: string,
+    args: JSONObject,
+    sklEngine: any,
+    capabilityConfig?: CapabilityConfig
+  ): Promise<OrArray<NodeObject>> {
+    const handler = this.customCapabilities.get(capabilityId);
+    if (!handler) {
+      throw new Error(`Custom capability '${capabilityId}' not found`);
+    }
+    return await handler(args, sklEngine, capabilityConfig);
+  }
+
+  public getAll(): string[] {
+    return [ ...this.customCapabilities.keys() ];
+  }
+
+  public clear(): void {
+    this.customCapabilities.clear();
+  }
+}
+
+// Global instance
+const globalCustomCapabilities = new GlobalCustomCapabilitiesRegistry();
+
+// Export functions for external use
+export const customCapabilities = {
+  register(capabilityId: string, handler: CustomCapabilityHandler): void {
+    globalCustomCapabilities.register(capabilityId, handler);
+  },
+  unregister: (capabilityId: string): boolean => globalCustomCapabilities.unregister(capabilityId),
+  has: (capabilityId: string): boolean => globalCustomCapabilities.has(capabilityId),
+  getAll: (): string[] => globalCustomCapabilities.getAll(),
+  clear: (): void => globalCustomCapabilities.clear()
+};
+
+// Export the registry instance for internal use
+export { globalCustomCapabilities };

package/src/examples/customCapabilitiesExample.ts

@@ -0,0 +1,77 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable no-console */
+
+import type { NodeObject } from 'jsonld';
+import type { SKLEngine } from '../index';
+import { customCapabilities } from '../index';
+import type { JSONObject } from '../util/Types';
+
+// Example 1: Simple custom capability
+customCapabilities.register('greetUser', async(args: JSONObject): Promise<NodeObject> => ({
+  '@type': 'GreetingResult',
+  '@value': `Hello, ${args.name as string}! Welcome to SKL Engine.`
+}));
+
+// Example 2: Custom capability that uses SKL Engine instance
+customCapabilities.register(
+  'countEntitiesWithProcessing',
+  async(args: JSONObject, sklEngine: SKLEngine): Promise<NodeObject> => {
+    try {
+      // Use the SKL engine to count entities
+      const count = await sklEngine.count(args);
+
+      // Add some processing
+      const processedCount = count * 2;
+
+      return {
+        '@type': 'ProcessedCountResult',
+        '@value': {
+          originalCount: count,
+          processedCount,
+          timestamp: new Date().toISOString()
+        }
+      };
+    } catch (error: unknown) {
+      return {
+        '@type': 'ErrorResult',
+        '@value': {
+          error: error instanceof Error ? error.message : 'Unknown error',
+          timestamp: new Date().toISOString()
+        }
+      };
+    }
+  }
+);
+
+// Example 3: Custom capability that returns multiple results
+customCapabilities.register(
+  'generateMultipleGreetings',
+  async(args: JSONObject): Promise<NodeObject[]> => {
+    const names = args.names as string[] || [];
+
+    return names.map((name, index) => ({
+      '@type': 'IndexedGreeting',
+      '@value': {
+        index,
+        message: `Hello, ${name}!`,
+        timestamp: new Date().toISOString()
+      }
+    }));
+  }
+);
+
+// Usage example:
+console.log('Custom capabilities registered:');
+console.log('- greetUser');
+console.log('- countEntitiesWithProcessing');
+console.log('- generateMultipleGreetings');
+
+console.log('\nAll registered capabilities:', customCapabilities.getAll());
+
+// Check if capabilities exist
+console.log('\nCapability checks:');
+console.log('greetUser exists:', customCapabilities.has('greetUser'));
+console.log('nonExistent exists:', customCapabilities.has('nonExistent'));
+
+export { };
+

package/src/hooks/globalHooks.ts

@@ -0,0 +1,238 @@
+/* eslint-disable id-length */
+/* eslint-disable symbol-description */
+/* eslint-disable @typescript-eslint/explicit-member-accessibility */
+/* eslint-disable @typescript-eslint/naming-convention */
+import type { CapabilityMapping, Entity } from '../util/Types';
+import type { SklHookContext } from './types';
+
+// Use symbols for hook types to avoid string collisions
+export const HookTypes = {
+  CREATE: Symbol('create'),
+  READ: Symbol('read'),
+  UPDATE: Symbol('update'),
+  DELETE: Symbol('delete'),
+  EXECUTE_CAPABILITY_MAPPING: Symbol('executeCapabilityMapping')
+};
+
+export const HookStages = {
+  BEFORE: Symbol('before'),
+  AFTER: Symbol('after'),
+  ERROR: Symbol('error')
+};
+
+// Hook function types
+export type GlobalBeforeHook = (context: SklHookContext) => Promise<void> | void;
+export type GlobalAfterHook = (context: SklHookContext, result: any) => Promise<any> | any;
+export type GlobalErrorHook = (context: SklHookContext, error: Error) => Promise<void> | void;
+export type GlobalExecuteCapabilityHook = (
+  context: SklHookContext,
+  capabilityMapping: CapabilityMapping,
+) => Promise<void> | void;
+// Hook registry entry type with metadata
+interface HookEntry {
+  id: symbol;
+  fn: GlobalBeforeHook | GlobalAfterHook | GlobalErrorHook;
+  priority: number;
+}
+
+// Registry to store global hooks
+class GlobalHooksRegistry {
+  private readonly hooks: Map<symbol, Map<symbol, HookEntry[]>> = new Map();
+
+  constructor() {
+    // Initialize hook maps for all CRUD operations and stages
+    Object.values(HookTypes).forEach(type => {
+      this.hooks.set(type, new Map());
+      Object.values(HookStages).forEach(stage => {
+        this.hooks.get(type)!.set(stage, []);
+      });
+    });
+  }
+
+  /**
+   * Register a hook with optional priority (higher runs first)
+   */
+  register(
+    type: symbol,
+    stage: symbol,
+    hook: GlobalBeforeHook | GlobalAfterHook | GlobalErrorHook,
+    priority = 0
+  ): symbol {
+    const hookId = Symbol();
+    const hooksList = this.hooks.get(type)?.get(stage);
+
+    if (!hooksList) {
+      throw new Error(`Invalid hook type or stage`);
+    }
+
+    hooksList.push({
+      id: hookId,
+      fn: hook,
+      priority
+    });
+
+    // Sort by priority (descending)
+    hooksList.sort((a, b) => b.priority - a.priority);
+
+    return hookId;
+  }
+
+  /**
+   * Unregister a hook by its ID
+   */
+  unregister(hookId: symbol): boolean {
+    let removed = false;
+
+    this.hooks.forEach(stageMap => {
+      stageMap.forEach(hooksList => {
+        const index = hooksList.findIndex(entry => entry.id === hookId);
+        if (index !== -1) {
+          hooksList.splice(index, 1);
+          removed = true;
+        }
+      });
+    });
+
+    return removed;
+  }
+
+  /**
+   * Execute hooks for a specific operation and stage
+   */
+  async execute(type: symbol, stage: symbol, context: SklHookContext, resultOrError?: any): Promise<any> {
+    const hooksList = this.hooks.get(type)?.get(stage);
+
+    if (!hooksList || hooksList.length === 0) {
+      return resultOrError;
+    }
+
+    if (stage === HookStages.BEFORE) {
+      for (const entry of hooksList) {
+        await (entry.fn as GlobalBeforeHook)(context);
+      }
+      return resultOrError;
+    }
+    if (stage === HookStages.AFTER) {
+      let result = resultOrError;
+      for (const entry of hooksList) {
+        const newResult = await (entry.fn as GlobalAfterHook)(context, result);
+        if (newResult !== undefined) {
+          result = newResult;
+        }
+      }
+      return result;
+    }
+    if (stage === HookStages.ERROR) {
+      for (const entry of hooksList) {
+        await (entry.fn as GlobalErrorHook)(context, resultOrError);
+      }
+      return resultOrError;
+    }
+
+    return resultOrError;
+  }
+
+  // Convenience methods for common operations
+  registerBeforeCreate(hook: GlobalBeforeHook, priority?: number): symbol {
+    return this.register(HookTypes.CREATE, HookStages.BEFORE, hook, priority);
+  }
+
+  registerAfterCreate(hook: GlobalAfterHook, priority?: number): symbol {
+    return this.register(HookTypes.CREATE, HookStages.AFTER, hook, priority);
+  }
+
+  registerErrorCreate(hook: GlobalErrorHook, priority?: number): symbol {
+    return this.register(HookTypes.CREATE, HookStages.ERROR, hook, priority);
+  }
+
+  // Additional convenience methods for other CRUD operations
+  registerBeforeRead(hook: GlobalBeforeHook, priority?: number): symbol {
+    return this.register(HookTypes.READ, HookStages.BEFORE, hook, priority);
+  }
+
+  // ... other convenience methods for read, update, delete operations
+
+  // Convenience methods for execute capability operations
+  registerBeforeExecuteCapabilityMapping(hook: GlobalExecuteCapabilityHook, priority?: number): symbol {
+    return this.register(HookTypes.EXECUTE_CAPABILITY_MAPPING, HookStages.BEFORE, hook, priority);
+  }
+
+  registerAfterExecuteCapabilityMapping(hook: GlobalAfterHook, priority?: number): symbol {
+    return this.register(HookTypes.EXECUTE_CAPABILITY_MAPPING, HookStages.AFTER, hook, priority);
+  }
+
+  registerErrorExecuteCapabilityMapping(hook: GlobalErrorHook, priority?: number): symbol {
+    return this.register(HookTypes.EXECUTE_CAPABILITY_MAPPING, HookStages.ERROR, hook, priority);
+  }
+
+  // Execution convenience methods
+  async executeBeforeCreate(entities: Entity[]): Promise<void> {
+    await this.execute(HookTypes.CREATE, HookStages.BEFORE, { entities, operation: 'save', operationParameters: {}});
+  }
+
+  async executeAfterCreate(entities: Entity | Entity[]): Promise<any> {
+    if (!Array.isArray(entities)) {
+      entities = [ entities ];
+    }
+    return this.execute(
+      HookTypes.CREATE,
+      HookStages.AFTER,
+      { entities, operation: 'save', operationParameters: {}},
+      entities
+    );
+  }
+
+  async executeErrorCreate(entities: Entity[], error: Error): Promise<void> {
+    await this.execute(
+      HookTypes.CREATE,
+      HookStages.ERROR,
+      { entities, operation: 'save', operationParameters: {}},
+      error
+    );
+  }
+
+  async executeBeforeExecuteCapabilityMapping(entities: Entity[], capabilityMapping: CapabilityMapping): Promise<void> {
+    await this.execute(HookTypes.EXECUTE_CAPABILITY_MAPPING, HookStages.BEFORE, {
+      entities,
+      operation: 'executeCapabilityMapping',
+      operationParameters: { capabilityMapping }
+    });
+  }
+
+  async executeAfterExecuteCapabilityMapping(
+    entities: Entity[],
+    capabilityMapping: CapabilityMapping,
+    result: any
+  ): Promise<any> {
+    return this.execute(
+      HookTypes.EXECUTE_CAPABILITY_MAPPING,
+      HookStages.AFTER,
+      {
+        entities,
+        operation: 'executeCapabilityMapping',
+        operationParameters: { capabilityMapping }
+      },
+      result
+    );
+  }
+
+  async executeErrorExecuteCapabilityMapping(
+    entities: Entity[],
+    capabilityMapping: CapabilityMapping,
+    error: Error
+  ): Promise<void> {
+    await this.execute(
+      HookTypes.EXECUTE_CAPABILITY_MAPPING,
+      HookStages.ERROR,
+      {
+        entities,
+        operation: 'executeCapabilityMapping',
+        operationParameters: { capabilityMapping }
+      },
+      error
+    );
+  }
+}
+
+// Export a singleton instance
+export const globalHooks = new GlobalHooksRegistry();

package/src/hooks/types.ts

@@ -0,0 +1,7 @@
+import type { Entity } from '../util/Types';
+
+export type SklHookContext = {
+  entities: Entity[];
+  operation: string;
+  operationParameters: Record<string, any>;
+};

package/src/index.ts

@@ -0,0 +1,45 @@
+// Mapping
+export * from './constants';
+export { customCapabilities, type CustomCapabilityHandler } from './customCapabilities';
+export { globalHooks as SklHooks, HookStages, HookTypes } from './hooks/globalHooks';
+export * from './hooks/types';
+// Code Executor
+export * from './JsExecutor';
+export * from './mapping/Mapper';
+export * from './SklEngine';
+// Storage
+export * from './storage/FindOperator';
+export * from './storage/FindOptionsTypes';
+export * from './storage/operator/And';
+export * from './storage/operator/Contains';
+// Storage/Operator
+export * from './storage/operator/Equal';
+export * from './storage/operator/Exists';
+export * from './storage/operator/GreaterThan';
+export * from './storage/operator/GreaterThanOrEqual';
+export * from './storage/operator/In';
+export * from './storage/operator/Inverse';
+export * from './storage/operator/InversePath';
+export * from './storage/operator/InverseRelation';
+export * from './storage/operator/InverseRelationOrder';
+export * from './storage/operator/LessThan';
+export * from './storage/operator/LessThanOrEqual';
+export * from './storage/operator/Not';
+export * from './storage/operator/OneOrMorePath';
+export * from './storage/operator/Sequence';
+export * from './storage/operator/SequencePath';
+export * from './storage/operator/ZeroOrMorePath';
+export * from './storage/query-adapter/QueryAdapter';
+export * from './storage/query-adapter/sparql/query-executor/InMemorySparqlQueryExecutor';
+export * from './storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor';
+// Storage/Sparql
+export * from './storage/query-adapter/sparql/SparqlQueryAdapter';
+export * from './storage/query-adapter/sparql/SparqlQueryBuilder';
+export * from './storage/query-adapter/sparql/SparqlUpdateBuilder';
+export * from './storage/query-adapter/sparql/VariableGenerator';
+// Util
+export * from './util/TripleUtil';
+export * from './util/Types';
+export * from './util/Util';
+export * from './util/Vocabularies/helper';
+