@comake/skl-js-engine 1.4.2 → 1.5.0

package/src/SklEngine.ts

@@ -34,7 +34,7 @@ import type { ExecutionOptions } from './JsExecutor';
 import type { ICodeExecutor } from './JsExecutor/types';
 import { Logger } from './logger';
 import { Mapper } from './mapping/Mapper';
-import type { SklEngineOptions } from './SklEngineOptions';
+import type { ReadCacheOperation, ReadCachePolicy, ReadCacheStore, SklEngineOptions } from './SklEngineOptions';
 import type { FindOperator } from './storage/FindOperator';
 import type { FindAllOptions, FindOneOptions, FindOptionsWhere } from './storage/FindOptionsTypes';
 import type { GroupByOptions, GroupByResponse } from './storage/GroupOptionTypes';
@@ -48,6 +48,7 @@ import { ZeroOrMorePath } from './storage/operator/ZeroOrMorePath';
 import type { QueryAdapter, RawQueryResult } from './storage/query-adapter/QueryAdapter';
 import { SparqlQueryAdapter } from './storage/query-adapter/sparql/SparqlQueryAdapter';
 import { PerformanceLogger } from './util/PerformanceLogger';
+import { buildReadCacheKey, ReadCacheSingleflight } from './util/ReadCacheHelper';
 // Import './util/safeJsonStringify';
 import type {
   Callbacks,
@@ -82,6 +83,7 @@ export type CapabilityInterface = Record<string, CapabilityHandler>;
 export type MappingResponseOption<T extends boolean> = T extends true ? JSONObject : NodeObject;
 
 export type WriteOptions = { bypassHooks?: boolean };
+const DEFAULT_READ_CACHE_TTL_MS = 60_000;
 
 export class SKLEngine implements SKLEngineInterface {
   private readonly queryAdapter: QueryAdapter;
@@ -94,6 +96,10 @@ export class SKLEngine implements SKLEngineInterface {
   private readonly skdsEndpointUrl: string;
   private readonly scriptPath: string;
   private readonly logger: Logger;
+  private readonly readCache?: ReadCacheStore;
+  private readonly readCachePolicy?: ReadCachePolicy;
+  private readonly readCacheNamespace?: string;
+  private readonly readCacheSingleflight = new ReadCacheSingleflight();
   public constructor(options: SklEngineOptions) {
     this.queryAdapter = new SparqlQueryAdapter(options);
     this.disableValidation = options.disableValidation;
@@ -101,6 +107,9 @@ export class SKLEngine implements SKLEngineInterface {
     this.inputFiles = options.inputFiles;
     this.skdsEndpointUrl = (options as any).endpointUrl;
     this.scriptPath = (options as any).scriptPath;
+    this.readCache = options.readCache;
+    this.readCachePolicy = options.readCachePolicy;
+    this.readCacheNamespace = options.readCacheNamespace;
     if (options.functions) {
       this.functions = Object.fromEntries(
         Object.entries(options.functions).map(([key, func]) => [
@@ -145,21 +154,120 @@ export class SKLEngine implements SKLEngineInterface {
     return await this.queryAdapter.executeRawConstructQuery(query, frame);
   }
 
+  private cloneForReadCache<T>(value: T): T {
+    try {
+      return structuredClone(value);
+    } catch {
+      return value;
+    }
+  }
+
+  private stripBypassCacheFromFindOneOptions(options?: FindOneOptions): FindOneOptions | undefined {
+    if (!options) {
+      return options;
+    }
+    const { bypassCache, ...rest } = options;
+    return rest;
+  }
+
+  private stripBypassCacheFromFindAllOptions(options?: FindAllOptions): FindAllOptions | undefined {
+    if (!options) {
+      return options;
+    }
+    const { bypassCache, ...rest } = options;
+    return rest;
+  }
+
+  private stripBypassCacheFromWhere(where?: FindOptionsWhere): FindOptionsWhere | undefined {
+    if (!where) {
+      return where;
+    }
+    const { bypassCache, ...rest } = where;
+    return rest;
+  }
+
+  private async runReadWithCache<T>(params: {
+    operation: ReadCacheOperation;
+    args: readonly unknown[];
+    bypassCache?: boolean;
+    execute: () => Promise<T>;
+  }): Promise<T> {
+    if (params.bypassCache) {
+      return await params.execute();
+    }
+
+    if (!this.readCache || !this.readCachePolicy) {
+      return await params.execute();
+    }
+
+    const policyDecision = this.readCachePolicy({
+      operation: params.operation,
+      args: params.args,
+      endpointUrl: this.skdsEndpointUrl,
+      namespace: this.readCacheNamespace
+    });
+    if (!policyDecision.cache) {
+      return await params.execute();
+    }
+
+    const ttlMs = policyDecision.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS;
+    if (ttlMs <= 0) {
+      return await params.execute();
+    }
+
+    const cacheKey = buildReadCacheKey({
+      operation: params.operation,
+      args: params.args,
+      endpointUrl: this.skdsEndpointUrl,
+      namespace: this.readCacheNamespace,
+      keyHint: policyDecision.keyHint
+    });
+
+    return await this.readCacheSingleflight.do(cacheKey, async() => {
+      try {
+        const cached = await this.readCache?.get(cacheKey);
+        if (cached !== undefined) {
+          return this.cloneForReadCache(cached as T);
+        }
+      } catch (error) {
+        this.logger.debug('Read cache lookup failed; continuing without cache', error as any);
+      }
+
+      const result = await params.execute();
+
+      try {
+        await this.readCache?.set(cacheKey, this.cloneForReadCache(result), ttlMs);
+      } catch (error) {
+        this.logger.debug('Read cache write failed; continuing without cache', error as any);
+      }
+
+      return result;
+    });
+  }
+
   public async find(options?: FindOneOptions): Promise<Entity> {
+    const bypassCache = options?.bypassCache;
+    const optionsWithoutBypass = this.stripBypassCacheFromFindOneOptions(options);
+
     return PerformanceLogger.withSpanRoot('SklEngine.find', async() => {
       const context = {
         entities: [],
         operation: 'find',
-        operationParameters: { options },
+        operationParameters: { options: optionsWithoutBypass },
         sklEngine: this
       };
 
       await globalHooks.execute(HookTypes.READ, HookStages.BEFORE, context);
 
       try {
-        const entity = await this.queryAdapter.find(options);
+        const entity = await this.runReadWithCache({
+          operation: 'find',
+          args: [optionsWithoutBypass],
+          bypassCache,
+          execute: async() => await this.queryAdapter.find(optionsWithoutBypass)
+        });
         if (!entity) {
-          throw new Error(`No schema found with fields matching ${JSON.stringify(options)}`);
+          throw new Error(`No schema found with fields matching ${JSON.stringify(optionsWithoutBypass)}`);
         }
 
         const updatedContext = { ...context, entities: [entity]};
@@ -170,31 +278,39 @@ export class SKLEngine implements SKLEngineInterface {
         await globalHooks.execute(HookTypes.READ, HookStages.ERROR, context, error);
         throw error;
       }
-    }, { options });
+    }, { options: optionsWithoutBypass });
   }
 
   public async findBy(where: FindOptionsWhere, notFoundErrorMessage?: string): Promise<Entity> {
+    const bypassCache = where?.bypassCache;
+    const whereWithoutBypass = this.stripBypassCacheFromWhere(where)!;
+
     return PerformanceLogger.withSpanRoot('SklEngine.findBy', async() => {
       const context = {
         entities: [],
         operation: 'findBy',
-        operationParameters: { where },
+        operationParameters: { where: whereWithoutBypass },
         sklEngine: this
       };
       await globalHooks.execute(HookTypes.READ, HookStages.BEFORE, context);
       try {
-        const entity = await this.queryAdapter.findBy(where);
+        const entity = await this.runReadWithCache({
+          operation: 'findBy',
+          args: [whereWithoutBypass, notFoundErrorMessage],
+          bypassCache,
+          execute: async() => await this.queryAdapter.findBy(whereWithoutBypass)
+        });
         if (entity) {
           const updatedContext = { ...context, entities: [entity]};
           await globalHooks.execute(HookTypes.READ, HookStages.AFTER, updatedContext, entity);
           return entity;
         }
-        throw new Error(notFoundErrorMessage ?? `No schema found with fields matching ${JSON.stringify(where)}`);
+        throw new Error(notFoundErrorMessage ?? `No schema found with fields matching ${JSON.stringify(whereWithoutBypass)}`);
       } catch (error: unknown) {
         await globalHooks.execute(HookTypes.READ, HookStages.ERROR, context, error);
         throw error;
       }
-    }, { where });
+    }, { where: whereWithoutBypass });
   }
 
   public async findByIfExists(options: FindOptionsWhere): Promise<Entity | undefined> {
@@ -207,16 +323,24 @@ export class SKLEngine implements SKLEngineInterface {
   }
 
   public async findAll(options?: FindAllOptions): Promise<Entity[]> {
+    const bypassCache = options?.bypassCache;
+    const optionsWithoutBypass = this.stripBypassCacheFromFindAllOptions(options);
+
     return PerformanceLogger.withSpanRoot('SklEngine.findAll', async() => {
       const context = {
         entities: [],
         operation: 'findAll',
-        operationParameters: { options },
+        operationParameters: { options: optionsWithoutBypass },
         sklEngine: this
       };
       await globalHooks.execute(HookTypes.READ, HookStages.BEFORE, context);
       try {
-        const entities = await this.queryAdapter.findAll(options);
+        const entities = await this.runReadWithCache({
+          operation: 'findAll',
+          args: [optionsWithoutBypass],
+          bypassCache,
+          execute: async() => await this.queryAdapter.findAll(optionsWithoutBypass)
+        });
         const updatedContext = { ...context, entities };
         await globalHooks.execute(HookTypes.READ, HookStages.AFTER, updatedContext, entities);
         return entities;
@@ -224,7 +348,7 @@ export class SKLEngine implements SKLEngineInterface {
         await globalHooks.execute(HookTypes.READ, HookStages.ERROR, context, error);
         throw error;
       }
-    }, { options });
+    }, { options: optionsWithoutBypass });
   }
 
   public async groupBy(options: GroupByOptions): Promise<GroupByResponse> {
@@ -274,7 +398,20 @@ export class SKLEngine implements SKLEngineInterface {
   }
 
   public async count(options?: FindAllOptions): Promise<number> {
-    return PerformanceLogger.withSpanRoot('SklEngine.count', async() => this.queryAdapter.count(options), { options });
+    const bypassCache = options?.bypassCache;
+    const optionsWithoutBypass = this.stripBypassCacheFromFindAllOptions(options);
+
+    return PerformanceLogger.withSpanRoot(
+      'SklEngine.count',
+      async() =>
+        await this.runReadWithCache({
+          operation: 'count',
+          args: [optionsWithoutBypass],
+          bypassCache,
+          execute: async() => await this.queryAdapter.count(optionsWithoutBypass)
+        }),
+      { options: optionsWithoutBypass }
+    );
   }
 
   public async save(entity: Entity, options?: WriteOptions): Promise<Entity>;

package/src/SklEngineOptions.ts

@@ -1,6 +1,30 @@
 import type { SparqlQueryAdapterOptions } from './storage/query-adapter/sparql/SparqlQueryAdapterOptions';
 import type { Callbacks } from './util/Types';
 
+export type ReadCacheOperation = 'find' | 'findBy' | 'findAll' | 'count';
+
+export interface ReadCacheStore {
+  get: (key: string) => Promise<unknown | undefined>;
+  set: (key: string, value: unknown, ttlMs: number) => Promise<void>;
+  delete?: (key: string) => Promise<void>;
+  clear?: () => Promise<void>;
+}
+
+export interface ReadCachePolicyInput {
+  operation: ReadCacheOperation;
+  args: readonly unknown[];
+  endpointUrl?: string;
+  namespace?: string;
+}
+
+export interface ReadCachePolicyDecision {
+  cache: boolean;
+  ttlMs?: number;
+  keyHint?: string;
+}
+
+export type ReadCachePolicy = (input: ReadCachePolicyInput) => ReadCachePolicyDecision;
+
 export type SklEngineOptions = SparqlQueryAdapterOptions & {
   /**
    * Callbacks to execute upon events.
@@ -25,4 +49,20 @@ export type SklEngineOptions = SparqlQueryAdapterOptions & {
    * The path to the executor script.
    */
   readonly scriptPath?: string;
+
+  /**
+   * Optional read cache store used for select read operations.
+   * Cache decisions are made by readCachePolicy.
+   */
+  readonly readCache?: ReadCacheStore;
+
+  /**
+   * Optional policy that decides whether a given read operation should be cached.
+   */
+  readonly readCachePolicy?: ReadCachePolicy;
+
+  /**
+   * Optional namespace to scope cache keys (for example tenant/account isolation).
+   */
+  readonly readCacheNamespace?: string;
 };

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './hooks/types';
 export * from './JsExecutor';
 export * from './mapping/Mapper';
 export * from './SklEngine';
+export * from './SklEngineOptions';
 // Storage
 export * from './storage/FindOperator';
 export * from './storage/FindOptionsTypes';

package/src/storage/FindOptionsTypes.ts

@@ -15,6 +15,7 @@ export interface FindOneOptions {
   skipFraming?: boolean;
   group?: Variable;
   entitySelectVariable?: Variable;
+  bypassCache?: boolean;
 }
 
 export type FindOptionsRelationsValue =
@@ -78,7 +79,8 @@ export interface FindOptionsWhere {
   binds?: BindPattern[];
   and?: FindOptionsWhere[];
   or?: FindOptionsWhere[];
-  [k: string]: FindOptionsWhereField | BindPattern[] | FindOptionsWhere[] | undefined;
+  bypassCache?: boolean;
+  [k: string]: FindOptionsWhereField | BindPattern[] | FindOptionsWhere[] | boolean | undefined;
 }
 
 // Add these new types
@@ -106,4 +108,5 @@ export interface FindCountOptions {
   relations?: FindOptionsRelations;
   order?: FindOptionsOrder;
   offset?: number;
+  bypassCache?: boolean;
 }

package/src/storage/query-adapter/sparql/SparqlQueryBuilder.ts

@@ -341,6 +341,28 @@ export class SparqlQueryBuilder {
   }
 
   private createWhereQueryData(subject: Variable, where?: FindOptionsWhere, isTopLevel = false): WhereQueryData {
+
+    // Optimization: if the top-level where contains an ID constraint plus additional filters,
+    // also push the ID constraint into graphWhere. This allows the outer CONSTRUCT query
+    // to be restricted by VALUES (?entity) which can be substantially faster on some SPARQL backends.
+    //
+    // Non-breaking: keep the existing behavior where `id` participates in the main WHERE too.
+    if (isTopLevel && where && 'id' in where && Object.keys(where).length > 1) {
+      const { id, ...restWhere } = where as FindOptionsWhere & { id: IdFindOptionsWhereField };
+      if (id !== undefined) {
+        const idQueryData = this.createWhereQueryDataForIdValue(subject, id);
+        const restQueryData = this.createWhereQueryData(subject, restWhere, false);
+        return {
+          ...restQueryData,
+          values: [ ...idQueryData.values, ...restQueryData.values ],
+          filters: [ ...idQueryData.filters, ...restQueryData.filters ],
+          triples: [ ...idQueryData.triples, ...restQueryData.triples ],
+          graphValues: [ ...idQueryData.values, ...restQueryData.graphValues ],
+          graphFilters: [ ...idQueryData.filters, ...restQueryData.graphFilters ],
+          graphTriples: [ ...idQueryData.triples, ...restQueryData.graphTriples ]
+        };
+      }
+    }
     if (isTopLevel && Object.keys(where ?? {}).length === 1 && 'id' in where!) {
       const { values, filters, triples } = this.createWhereQueryDataForIdValue(subject, where.id!);
       return {