webspresso 0.0.64 → 0.0.66

package/core/orm/cache/memory-provider.js

@@ -0,0 +1,109 @@
+/**
+ * In-memory CacheProvider (process-local, tag-based invalidation)
+ * @module core/orm/cache/memory-provider
+ */
+
+/**
+ * @typedef {Object} MemoryCacheProviderOptions
+ * @property {number} [maxEntries=10000] - Max stored keys; FIFO evict on overflow
+ * @property {number} [defaultTtlMs=0] - Default TTL (0 = no expiry)
+ */
+
+/**
+ * @param {MemoryCacheProviderOptions} [options]
+ * @returns {import('./types').CacheProvider}
+ */
+function createMemoryCacheProvider(options = {}) {
+  const maxEntries = options.maxEntries ?? 10000;
+  const defaultTtlMs = options.defaultTtlMs ?? 0;
+
+  /** @type {Map<string, { value: *, expiresAt: number, tags: Set<string> }>} */
+  const store = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const tagToKeys = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const keyToTags = new Map();
+
+  function removeKey(key) {
+    const tags = keyToTags.get(key);
+    if (tags) {
+      for (const t of tags) {
+        const set = tagToKeys.get(t);
+        if (set) {
+          set.delete(key);
+          if (set.size === 0) tagToKeys.delete(t);
+        }
+      }
+    }
+    keyToTags.delete(key);
+    store.delete(key);
+  }
+
+  function get(key) {
+    const entry = store.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+      removeKey(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function set(key, value, opts = {}) {
+    const tags = Array.isArray(opts.tags) ? opts.tags : [];
+    const ttlMs = opts.ttlMs ?? defaultTtlMs;
+
+    if (store.has(key)) removeKey(key);
+
+    if (maxEntries > 0 && store.size >= maxEntries) {
+      const first = store.keys().next().value;
+      if (first !== undefined) removeKey(first);
+    }
+
+    const expiresAt = ttlMs > 0 ? Date.now() + ttlMs : 0;
+    const tagSet = new Set(tags);
+    store.set(key, { value, expiresAt, tags: tagSet });
+    keyToTags.set(key, new Set(tags));
+
+    for (const t of tags) {
+      if (!tagToKeys.has(t)) tagToKeys.set(t, new Set());
+      tagToKeys.get(t).add(key);
+    }
+  }
+
+  function invalidateTags(tags) {
+    const toDelete = new Set();
+    for (const t of tags) {
+      const keys = tagToKeys.get(t);
+      if (!keys) continue;
+      for (const k of keys) toDelete.add(k);
+    }
+    for (const k of toDelete) removeKey(k);
+    for (const t of tags) tagToKeys.delete(t);
+  }
+
+  function clear() {
+    store.clear();
+    tagToKeys.clear();
+    keyToTags.clear();
+  }
+
+  function getSizeStats() {
+    return {
+      entries: store.size,
+      tags: tagToKeys.size,
+    };
+  }
+
+  return {
+    get,
+    set,
+    invalidateTags,
+    clear,
+    getSizeStats,
+  };
+}
+
+module.exports = {
+  createMemoryCacheProvider,
+};

package/core/orm/cache/types.js

@@ -0,0 +1,27 @@
+/**
+ * @typedef {Object} CacheSetOptions
+ * @property {string[]} [tags]
+ * @property {number} [ttlMs]
+ */
+
+/**
+ * @typedef {Object} CacheProvider
+ * @property {(key: string) => *|undefined} get
+ * @property {(key: string, value: *, opts?: CacheSetOptions) => void} set
+ * @property {(tags: string[]) => void} invalidateTags
+ * @property {() => void} clear
+ * @property {() => { entries: number, tags: number }} getSizeStats
+ */
+
+/**
+ * @typedef {'auto'|'smart'} CacheStrategy
+ */
+
+/**
+ * @typedef {Object} OrmCacheConfigResolved
+ * @property {boolean} enabled
+ * @property {CacheStrategy} defaultStrategy
+ * @property {import('./memory-provider').MemoryCacheProviderOptions} [memoryOptions]
+ */
+
+module.exports = {};

package/core/orm/index.js

@@ -15,6 +15,7 @@ const { createScopeContext } = require('./scopes');
 const { ModelEvents, Hooks, HookCancellationError, createEventContext } = require('./events');
 const { omitHiddenColumns, sanitizeForOutput } = require('./utils');
 const { generateNanoid, zodNanoid, extendZ } = require('./utils/nanoid');
+const { createOrmCacheFromConfig, unregisterOrmCacheListeners } = require('./cache');
 
 /**
  * Create a database instance
@@ -93,6 +94,10 @@ function createDatabase(config) {
   const migrationConfig = config.migrations || {};
   const migrate = createMigrationManager(knexInstance, migrationConfig);
 
+  const { layer: ormCacheLayer, publicApi: ormCachePublicApi } = createOrmCacheFromConfig(
+    config.cache
+  );
+
   // Auto-load models from models directory
   const modelsDir = config.models || './models';
   const absoluteModelsDir = path.resolve(process.cwd(), modelsDir);
@@ -180,7 +185,7 @@ function createDatabase(config) {
     const model = getModelInstance(modelName);
     // Always create fresh scope context if not provided to avoid shared state
     const ctx = scopeContext || createScopeContext();
-    return createRepository(model, knexInstance, ctx);
+    return createRepository(model, knexInstance, ctx, ormCacheLayer);
   }
 
   /**
@@ -192,7 +197,7 @@ function createDatabase(config) {
   function query(modelName, scopeContext) {
     const model = getModelInstance(modelName);
     const ctx = scopeContext || createScopeContext();
-    const repo = createRepository(model, knexInstance, ctx);
+    const repo = createRepository(model, knexInstance, ctx, ormCacheLayer);
     return repo.query();
   }
 
@@ -212,7 +217,7 @@ function createDatabase(config) {
    */
   function createRepositoryFromModel(model, scopeContext) {
     const ctx = scopeContext || createScopeContext();
-    return createRepository(model, knexInstance, ctx);
+    return createRepository(model, knexInstance, ctx, ormCacheLayer);
   }
 
   /**
@@ -228,11 +233,11 @@ function createDatabase(config) {
         getRepository(modelName, scopeContext) {
           const model = getModelInstance(modelName);
           const ctx = scopeContext || createScopeContext();
-          return createRepository(model, trx, ctx);
+          return createRepository(model, trx, ctx, ormCacheLayer);
         },
         createRepository(model, scopeContext) {
           const ctx = scopeContext || createScopeContext();
-          return createRepository(model, trx, ctx);
+          return createRepository(model, trx, ctx, ormCacheLayer);
         },
       };
       return callback(trxContext);
@@ -251,7 +256,11 @@ function createDatabase(config) {
     query,
     transaction,
     createSeeder: createSeederInstance,
-    destroy: () => knexInstance.destroy(),
+    cache: ormCachePublicApi,
+    destroy: () => {
+      if (ormCacheLayer) unregisterOrmCacheListeners(ormCacheLayer);
+      return knexInstance.destroy();
+    },
   };
 }
 
@@ -262,6 +271,10 @@ const zdb = z ? createSchemaHelpers(z) : null;
 module.exports = {
   // Main factory
   createDatabase,
+  // ORM cache (provider + layer utilities)
+  createMemoryCacheProvider: require('./cache/memory-provider').createMemoryCacheProvider,
+  OrmCacheLayer: require('./cache/layer').OrmCacheLayer,
+  createOrmCacheFromConfig: require('./cache').createOrmCacheFromConfig,
   // Schema helpers
   zdb,
   createSchemaHelpers,

package/core/orm/model.js

@@ -30,6 +30,7 @@ function defineModel(options) {
     rest = {},
     hooks = {},
     hidden = [],
+    cache: cacheOption,
   } = options;
 
   // Validate required fields
@@ -97,6 +98,7 @@ function defineModel(options) {
     },
     hidden: Array.isArray(hidden) ? hidden : [],
     hooks: {},
+    cache: cacheOption,
   };
 
   // Register model

package/core/orm/query-builder.js

@@ -21,8 +21,8 @@ const {
  * @param {import('./types').ScopeContext} [initialContext] - Initial scope context
  * @returns {QueryBuilder}
  */
-function createQueryBuilder(model, knex, initialContext) {
-  return new QueryBuilder(model, knex, initialContext);
+function createQueryBuilder(model, knex, initialContext, cacheLayer = null) {
+  return new QueryBuilder(model, knex, initialContext, cacheLayer);
 }
 
 /**
@@ -34,11 +34,13 @@ class QueryBuilder {
    * @param {import('./types').ModelDefinition} model
    * @param {import('knex').Knex|import('knex').Knex.Transaction} knex
    * @param {import('./types').ScopeContext} [initialContext]
+   * @param {import('./cache/layer').OrmCacheLayer|null} [cacheLayer]
    */
-  constructor(model, knex, initialContext) {
+  constructor(model, knex, initialContext, cacheLayer = null) {
     this.model = model;
     this.knex = knex;
     this.scopeContext = initialContext || createScopeContext();
+    this.cacheLayer = cacheLayer;
     this.jsonColumns = getJsonColumns(model);
 
     /** @type {import('./types').QueryState} */
@@ -376,24 +378,64 @@ class QueryBuilder {
    */
   async first() {
     const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
-    await ModelEvents.emitAsync(this.model.name, Hooks.BEFORE_FIND, {}, ctx);
-    if (ctx.isCancelled) {
-      throw new HookCancellationError(ctx.cancelReason, this.model.name, Hooks.BEFORE_FIND);
-    }
+    const self = this;
+
+    async function loadFromDb() {
+      await ModelEvents.emitAsync(self.model.name, Hooks.BEFORE_FIND, {}, ctx);
+      if (ctx.isCancelled) {
+        throw new HookCancellationError(ctx.cancelReason, self.model.name, Hooks.BEFORE_FIND);
+      }
 
-    const qb = this.toKnex().first();
-    const result = await qb;
-    if (!result) return null;
+      const qb = self.toKnex().first();
+      const result = await qb;
+      if (!result) return null;
 
-    deserializeJsonFields(result, this.jsonColumns);
+      deserializeJsonFields(result, self.jsonColumns);
+
+      const withs = self.getWiths();
+      if (withs.length > 0) {
+        await loadRelations([result], ensureArray(withs), self.model, self.knex, self.scopeContext);
+      }
 
-    const withs = this.getWiths();
-    if (withs.length > 0) {
-      await loadRelations([result], ensureArray(withs), this.model, this.knex, this.scopeContext);
+      ModelEvents.emit(self.model.name, Hooks.AFTER_FIND, result, ctx);
+      return result;
     }
 
-    ModelEvents.emit(this.model.name, Hooks.AFTER_FIND, result, ctx);
-    return result;
+    if (
+      self.cacheLayer &&
+      self.cacheLayer.strategyFor(self.model)
+    ) {
+      const strat = self.cacheLayer.strategyFor(self.model);
+      const classification = self.cacheLayer.classifyQueryBuilder(self.model, self.state, 'first');
+      if (!classification.cacheable) {
+        self.cacheLayer.metrics.bypassed += 1;
+        return loadFromDb();
+      }
+      const kind = classification.kind === 'pk' ? 'pk' : 'collection';
+      const fingerprint = self.cacheLayer.queryBuilderFingerprint(
+        self.model,
+        self.scopeContext,
+        self.state,
+        'first'
+      );
+      const tags = self.cacheLayer.buildReadTags(
+        self.model,
+        strat,
+        kind,
+        classification.kind === 'pk' ? classification.pkValue : null
+      );
+      return self.cacheLayer.wrapRead(
+        self.model,
+        self.knex,
+        self.scopeContext,
+        fingerprint,
+        tags,
+        loadFromDb,
+        (r) => r != null
+      );
+    }
+
+    return loadFromDb();
   }
 
   /**
@@ -402,26 +444,57 @@ class QueryBuilder {
    */
   async list() {
     const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
-    await ModelEvents.emitAsync(this.model.name, Hooks.BEFORE_FIND, {}, ctx);
-    if (ctx.isCancelled) {
-      throw new HookCancellationError(ctx.cancelReason, this.model.name, Hooks.BEFORE_FIND);
-    }
+    const self = this;
 
-    const results = await this.toKnex();
+    async function loadFromDb() {
+      await ModelEvents.emitAsync(self.model.name, Hooks.BEFORE_FIND, {}, ctx);
+      if (ctx.isCancelled) {
+        throw new HookCancellationError(ctx.cancelReason, self.model.name, Hooks.BEFORE_FIND);
+      }
 
-    for (const record of results) {
-      deserializeJsonFields(record, this.jsonColumns);
-    }
+      const results = await self.toKnex();
 
-    const withs = this.getWiths();
-    if (withs.length > 0 && results.length > 0) {
-      await loadRelations(results, ensureArray(withs), this.model, this.knex, this.scopeContext);
+      for (const record of results) {
+        deserializeJsonFields(record, self.jsonColumns);
+      }
+
+      const withs = self.getWiths();
+      if (withs.length > 0 && results.length > 0) {
+        await loadRelations(results, ensureArray(withs), self.model, self.knex, self.scopeContext);
+      }
+
+      for (const record of results) {
+        ModelEvents.emit(self.model.name, Hooks.AFTER_FIND, record, ctx);
+      }
+      return results;
     }
 
-    for (const record of results) {
-      ModelEvents.emit(this.model.name, Hooks.AFTER_FIND, record, ctx);
+    if (self.cacheLayer && self.cacheLayer.strategyFor(self.model)) {
+      const strat = self.cacheLayer.strategyFor(self.model);
+      const classification = self.cacheLayer.classifyQueryBuilder(self.model, self.state, 'list');
+      if (!classification.cacheable) {
+        self.cacheLayer.metrics.bypassed += 1;
+        return loadFromDb();
+      }
+      const fingerprint = self.cacheLayer.queryBuilderFingerprint(
+        self.model,
+        self.scopeContext,
+        self.state,
+        'list'
+      );
+      const tags = self.cacheLayer.buildReadTags(self.model, strat, 'collection', null);
+      return self.cacheLayer.wrapRead(
+        self.model,
+        self.knex,
+        self.scopeContext,
+        fingerprint,
+        tags,
+        loadFromDb,
+        () => true
+      );
     }
-    return results;
+
+    return loadFromDb();
   }
 
   /**
@@ -437,8 +510,42 @@ class QueryBuilder {
    * @returns {Promise<number>}
    */
   async count() {
-    const result = await this.toKnex({ includeLimitOffset: false }).count('* as count').first();
-    return parseInt(result?.count || 0, 10);
+    const self = this;
+
+    async function loadFromDb() {
+      const result = await self
+        .toKnex({ includeLimitOffset: false })
+        .count('* as count')
+        .first();
+      return parseInt(result?.count || 0, 10);
+    }
+
+    if (self.cacheLayer && self.cacheLayer.strategyFor(self.model)) {
+      const strat = self.cacheLayer.strategyFor(self.model);
+      const classification = self.cacheLayer.classifyQueryBuilder(self.model, self.state, 'count');
+      if (!classification.cacheable) {
+        self.cacheLayer.metrics.bypassed += 1;
+        return loadFromDb();
+      }
+      const fingerprint = self.cacheLayer.queryBuilderFingerprint(
+        self.model,
+        self.scopeContext,
+        self.state,
+        'count'
+      );
+      const tags = self.cacheLayer.buildReadTags(self.model, strat, 'collection', null);
+      return self.cacheLayer.wrapRead(
+        self.model,
+        self.knex,
+        self.scopeContext,
+        fingerprint,
+        tags,
+        loadFromDb,
+        () => true
+      );
+    }
+
+    return loadFromDb();
   }
 
   /**
@@ -458,39 +565,71 @@ class QueryBuilder {
    */
   async paginate(page = 1, perPage = 15) {
     const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
-    await ModelEvents.emitAsync(this.model.name, Hooks.BEFORE_FIND, {}, ctx);
-    if (ctx.isCancelled) {
-      throw new HookCancellationError(ctx.cancelReason, this.model.name, Hooks.BEFORE_FIND);
-    }
+    const self = this;
+
+    async function loadFromDb() {
+      await ModelEvents.emitAsync(self.model.name, Hooks.BEFORE_FIND, {}, ctx);
+      if (ctx.isCancelled) {
+        throw new HookCancellationError(ctx.cancelReason, self.model.name, Hooks.BEFORE_FIND);
+      }
 
-    const base = this.toKnex({ includeLimitOffset: false });
+      const base = self.toKnex({ includeLimitOffset: false });
 
-    const countResult = await base.clone().count('* as count').first();
-    const total = parseInt(countResult?.count || 0, 10);
+      const countResult = await base.clone().count('* as count').first();
+      const total = parseInt(countResult?.count || 0, 10);
 
-    const offset = (page - 1) * perPage;
-    const data = await base.clone().limit(perPage).offset(offset);
+      const offset = (page - 1) * perPage;
+      const data = await base.clone().limit(perPage).offset(offset);
 
-    for (const record of data) {
-      deserializeJsonFields(record, this.jsonColumns);
-    }
+      for (const record of data) {
+        deserializeJsonFields(record, self.jsonColumns);
+      }
+
+      const withs = self.getWiths();
+      if (withs.length > 0 && data.length > 0) {
+        await loadRelations(data, ensureArray(withs), self.model, self.knex, self.scopeContext);
+      }
+
+      for (const record of data) {
+        ModelEvents.emit(self.model.name, Hooks.AFTER_FIND, record, ctx);
+      }
 
-    const withs = this.getWiths();
-    if (withs.length > 0 && data.length > 0) {
-      await loadRelations(data, ensureArray(withs), this.model, this.knex, this.scopeContext);
+      return {
+        data,
+        total,
+        page,
+        perPage,
+        totalPages: Math.ceil(total / perPage),
+      };
     }
 
-    for (const record of data) {
-      ModelEvents.emit(this.model.name, Hooks.AFTER_FIND, record, ctx);
+    if (self.cacheLayer && self.cacheLayer.strategyFor(self.model)) {
+      const strat = self.cacheLayer.strategyFor(self.model);
+      const classification = self.cacheLayer.classifyQueryBuilder(self.model, self.state, 'paginate');
+      if (!classification.cacheable) {
+        self.cacheLayer.metrics.bypassed += 1;
+        return loadFromDb();
+      }
+      const fingerprint = self.cacheLayer.queryBuilderFingerprint(
+        self.model,
+        self.scopeContext,
+        self.state,
+        'paginate',
+        { page, perPage }
+      );
+      const tags = self.cacheLayer.buildReadTags(self.model, strat, 'collection', null);
+      return self.cacheLayer.wrapRead(
+        self.model,
+        self.knex,
+        self.scopeContext,
+        fingerprint,
+        tags,
+        loadFromDb,
+        () => true
+      );
     }
 
-    return {
-      data,
-      total,
-      page,
-      perPage,
-      totalPages: Math.ceil(total / perPage),
-    };
+    return loadFromDb();
   }
 
   /**
@@ -498,7 +637,11 @@ class QueryBuilder {
    * @returns {Promise<number>} Number of deleted records
    */
   async delete() {
-    return this.toKnex().delete();
+    const n = await this.toKnex().delete();
+    if (this.cacheLayer && n > 0) {
+      this.cacheLayer.invalidateModelAll(this.model);
+    }
+    return n;
   }
 
   /**
@@ -508,7 +651,11 @@ class QueryBuilder {
    */
   async update(data) {
     const serialized = serializeJsonFields(data, this.jsonColumns);
-    return this.toKnex().update(serialized);
+    const n = await this.toKnex().update(serialized);
+    if (this.cacheLayer && n > 0) {
+      this.cacheLayer.invalidateModelAll(this.model);
+    }
+    return n;
   }
 
   /**
@@ -532,7 +679,7 @@ class QueryBuilder {
    * @returns {QueryBuilder}
    */
   clone() {
-    const cloned = new QueryBuilder(this.model, this.knex, { ...this.scopeContext });
+    const cloned = new QueryBuilder(this.model, this.knex, { ...this.scopeContext }, this.cacheLayer);
     cloned.jsonColumns = this.jsonColumns;
     cloned.state = {
       wheres: [...this.state.wheres],