@chainfuse/helpers 4.4.8 → 4.5.0

package/dist/db.d.mts

@@ -1,7 +1,7 @@
 import type { CacheStorageLike } from '@chainfuse/types';
 import { Cache as DrizzleCache, type MutationOption } from 'drizzle-orm/cache/core';
 import type { CacheConfig } from 'drizzle-orm/cache/core/types';
-import * as z from 'zod/mini';
+import * as zm from 'zod/mini';
 /**
  * SQLCache is a cache implementation for SQL query results, using Web CacheStorage (supports drop in replacements).
  * It supports caching strategies for explicit or global query caching, and provides mechanisms for cache invalidation based on affected tables or tags.
@@ -22,17 +22,16 @@ export declare class SQLCache<C extends CacheStorageLike> extends DrizzleCache {
     private _strategy;
     private logging;
     private usedTablesPerKey;
-    static constructorArgs: z.ZodMiniObject<{
-        dbName: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<string, string>>;
-        dbType: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<string, string>>;
-        cacheTTL: z.ZodMiniDefault<z.ZodMiniNumberFormat>;
-        cachePurge: z.ZodMiniDefault<z.ZodMiniUnion<readonly [z.ZodMiniBoolean<boolean>, z.ZodMiniDate<Date>]>>;
-        strategy: z.ZodMiniDefault<z.ZodMiniEnum<{
+    static constructorArgs: zm.ZodMiniObject<{
+        dbName: zm.ZodMiniPipe<zm.ZodMiniString<string>, zm.ZodMiniTransform<string, string>>;
+        dbType: zm.ZodMiniPipe<zm.ZodMiniString<string>, zm.ZodMiniTransform<string, string>>;
+        cacheTTL: zm.ZodMiniDefault<zm.ZodMiniNumberFormat>;
+        cachePurge: zm.ZodMiniDefault<zm.ZodMiniUnion<readonly [zm.ZodMiniBoolean<boolean>, zm.ZodMiniDate<Date>, zm.ZodMiniCodec<zm.z.iso.ZodMiniISODateTime, zm.ZodMiniDate<Date>>]>>;
+        strategy: zm.ZodMiniDefault<zm.ZodMiniEnum<{
             all: "all";
             explicit: "explicit";
         }>>;
-        logging: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
-    }, z.core.$strip>;
+    }, zm.z.core.$strip>;
     /**
      * Creates an instance of the class with the specified database name, type, and cache TTL.
      *
@@ -44,7 +43,7 @@ export declare class SQLCache<C extends CacheStorageLike> extends DrizzleCache {
      * - `all`: All queries are cached globally.
      * @param cacheStore - The cache store to use. Can be a CacheStorage or CacheStorage-like object that atleast contains the `open()` function
      */
-    constructor(args: z.input<(typeof SQLCache)['constructorArgs']>, cacheStore?: C);
+    constructor(args: zm.input<(typeof SQLCache)['constructorArgs']>, cacheStore?: C);
     /**
      * For the strategy, we have two options:
      * - `explicit`: The cache is used only when .$withCache() is added to a query.
@@ -52,6 +51,7 @@ export declare class SQLCache<C extends CacheStorageLike> extends DrizzleCache {
      * @default 'explicit'
      */
     strategy(): "all" | "explicit";
+    private log;
     /**
      * Generates a cache key as a `Request` object based on the provided tag or key.
      *

package/dist/db.mjs

@@ -1,7 +1,8 @@
 import { Cache as DrizzleCache } from 'drizzle-orm/cache/core';
 import { is } from 'drizzle-orm/entity';
 import { getTableName, Table } from 'drizzle-orm/table';
-import * as z from 'zod/mini';
+import { channel } from 'node:diagnostics_channel';
+import * as zm from 'zod/mini';
 import { CryptoHelpers } from "./crypto.mjs";
 /**
  * SQLCache is a cache implementation for SQL query results, using Web CacheStorage (supports drop in replacements).
@@ -21,16 +22,26 @@ export class SQLCache extends DrizzleCache {
     globalTtl;
     ttlCutoff;
     _strategy;
-    logging;
+    logging = {
+        'SQLCache:GET': channel('SQLCache:GET'),
+        'SQLCache:PUT': channel('SQLCache:PUT'),
+        'SQLCache:DELETE': channel('SQLCache:DELETE'),
+    };
     // This object will be used to store which query keys were used for a specific table, so we can later use it for invalidation.
     usedTablesPerKey = {};
-    static constructorArgs = z.object({
-        dbName: z.pipe(z.string().check(z.trim(), z.minLength(1)), z.transform((val) => encodeURIComponent(val))),
-        dbType: z.pipe(z.string().check(z.trim(), z.minLength(1)), z.transform((val) => encodeURIComponent(val))),
-        cacheTTL: z._default(z.int().check(z.nonnegative()), 5 * 60),
-        cachePurge: z._default(z.union([z.boolean(), z.date()]), false),
-        strategy: z._default(z.enum(['explicit', 'all']), 'explicit'),
-        logging: z._default(z.boolean(), false),
+    static constructorArgs = zm.object({
+        dbName: zm.pipe(zm.string().check(zm.trim(), zm.minLength(1)), zm.transform((val) => encodeURIComponent(val))),
+        dbType: zm.pipe(zm.string().check(zm.trim(), zm.minLength(1)), zm.transform((val) => encodeURIComponent(val))),
+        cacheTTL: zm._default(zm.int().check(zm.nonnegative()), 5 * 60),
+        cachePurge: zm._default(zm.union([
+            zm.boolean(),
+            zm.date(),
+            zm.codec(zm.iso.datetime({ precision: 3, local: false, offset: false }), zm.date(), {
+                decode: (isoString) => new Date(isoString),
+                encode: (date) => date.toISOString(),
+            }),
+        ]), false),
+        strategy: zm._default(zm.enum(['explicit', 'all']), 'explicit'),
     });
     /**
      * Creates an instance of the class with the specified database name, type, and cache TTL.
@@ -45,7 +56,7 @@ export class SQLCache extends DrizzleCache {
      */
     constructor(args, cacheStore) {
         super();
-        const { dbName, dbType, cacheTTL, cachePurge, strategy, logging } = SQLCache.constructorArgs.parse(args);
+        const { dbName, dbType, cacheTTL, cachePurge, strategy } = SQLCache.constructorArgs.parse(args);
         this.dbName = dbName;
         this.dbType = dbType;
         cacheStore ??= globalThis.caches;
@@ -58,7 +69,10 @@ export class SQLCache extends DrizzleCache {
         this.globalTtl = cacheTTL;
         this.ttlCutoff = cachePurge;
         this._strategy = strategy;
-        this.logging = logging;
+        this.logging[`SQLCache:${this.dbName}.${this.dbType}:GET`] = channel(`SQLCache:${this.dbName}.${this.dbType}:GET`);
+        this.logging[`SQLCache:${this.dbName}.${this.dbType}:PUT`] = channel(`SQLCache:${this.dbName}.${this.dbType}:PUT`);
+        this.logging[`SQLCache:${this.dbName}.${this.dbType}:DELETE`] = channel(`SQLCache:${this.dbName}.${this.dbType}:DELETE`);
+        console.debug('SQLCache available logging channels', Object.keys(this.logging));
     }
     /**
      * For the strategy, we have two options:
@@ -69,6 +83,10 @@ export class SQLCache extends DrizzleCache {
     strategy() {
         return this._strategy;
     }
+    log(type, message) {
+        this.logging[`SQLCache:${this.dbName}.${this.dbType}:${type}`]?.publish(message);
+        this.logging[`SQLCache:${type}`].publish({ db: `${this.dbName}.${this.dbType}`, ...message });
+    }
     /**
      * Generates a cache key as a `Request` object based on the provided tag or key.
      *
@@ -89,37 +107,39 @@ export class SQLCache extends DrizzleCache {
     async get(key, _tables, isTag) {
         const cacheKey = this.getCacheKey(isTag ? { tag: key } : { key });
         const response = await this.cache.then(async (cache) => cache.match(cacheKey));
-        if (this.logging)
-            console.debug('SQLCache.get', isTag ? 'tag' : 'key', key, response?.ok ? 'HIT' : 'MISS');
         if (response) {
             // Check if cache should be purged
             if (this.ttlCutoff === true) {
-                if (this.logging)
-                    console.debug('SQLCache.get', 'cache purged', this.ttlCutoff);
-                await this.cache.then((cache) => cache.delete(cacheKey));
+                this.log('GET', { keyType: isTag ? 'tag' : 'key', key, status: 'EXPIRED', expires: new Date().toISOString() });
+                const deleted = await this.cache.then((cache) => cache.delete(cacheKey));
+                this.log('DELETE', { keyType: isTag ? 'tag' : 'key', key, status: deleted ? 'DELETED' : 'NOT_FOUND', reason: 'TTL Cutoff parameter is true' });
+                return undefined;
+            }
+            // If the response doesn't have a Date header, we can't check its age, so we will consider it malformed and remove it from the cache to avoid future issues.
+            if (!response.headers.has('Date')) {
+                this.log('GET', { keyType: isTag ? 'tag' : 'key', key, status: 'UNKNOWN' });
+                const deleted = await this.cache.then((cache) => cache.delete(cacheKey));
+                this.log('DELETE', { keyType: isTag ? 'tag' : 'key', key, status: deleted ? 'DELETED' : 'NOT_FOUND', reason: 'Malformed cached response' });
                 return undefined;
             }
+            const cachedDate = new Date(response.headers.get('Date'));
             if (this.ttlCutoff instanceof Date) {
-                const responseDate = response.headers.get('Date');
-                if (responseDate) {
-                    const cachedDate = new Date(responseDate);
-                    if (cachedDate < this.ttlCutoff) {
-                        if (this.logging)
-                            console.debug('SQLCache.get', 'cache purged', { cachedDate, cutoff: this.ttlCutoff });
-                        await this.cache.then((cache) => cache.delete(cacheKey));
-                        return undefined;
-                    }
-                }
-                else {
-                    if (this.logging)
-                        console.debug('SQLCache.get', 'cache purged', { responseDate });
-                    await this.cache.then((cache) => cache.delete(cacheKey));
+                if (cachedDate < this.ttlCutoff) {
+                    this.log('GET', { keyType: isTag ? 'tag' : 'key', key, status: 'EXPIRED', expires: this.ttlCutoff.toISOString() });
+                    const deleted = await this.cache.then((cache) => cache.delete(cacheKey));
+                    this.log('DELETE', { keyType: isTag ? 'tag' : 'key', key, status: deleted ? 'DELETED' : 'NOT_FOUND', reason: `Cached date ${cachedDate.toISOString()} is older than TTL cutoff ${this.ttlCutoff.toISOString()} by ${(this.ttlCutoff.getTime() - cachedDate.getTime()) / 1000} seconds` });
                     return undefined;
                 }
             }
+            const cacheControl = response.headers.get('Cache-Control');
+            const sMaxAge = /(?:^|,)\s*s-maxage=(\d+)\b/i.exec(cacheControl)?.at(1);
+            const maxAge = /(?:^|,)\s*max-age=(\d+)\b/i.exec(cacheControl)?.at(1);
+            const maxAgeSeconds = sMaxAge !== undefined ? Number.parseInt(sMaxAge, 10) : maxAge !== undefined ? Number.parseInt(maxAge, 10) : undefined;
+            this.log('GET', { keyType: isTag ? 'tag' : 'key', key, status: 'HIT', ...(maxAgeSeconds !== undefined && { expires: new Date(cachedDate.getTime() + maxAgeSeconds * 1000).toISOString() }) });
             return response.json();
         }
         else {
+            this.log('GET', { keyType: isTag ? 'tag' : 'key', key, status: 'MISS' });
             return undefined;
         }
     }
@@ -153,12 +173,8 @@ export class SQLCache extends DrizzleCache {
             },
         });
         cacheResponse.headers.set('ETag', await CryptoHelpers.generateETag(cacheResponse));
-        await this.cache
-            .then(async (cache) => cache.put(this.getCacheKey(isTag ? { tag: hashedQuery } : { key: hashedQuery }), cacheResponse))
-            .then(() => {
-            if (this.logging)
-                console.debug('SQLCache.put', isTag ? 'tag' : 'key', hashedQuery, 'SUCCESS');
-        });
+        await this.cache.then(async (cache) => cache.put(this.getCacheKey(isTag ? { tag: hashedQuery } : { key: hashedQuery }), cacheResponse));
+        this.log('PUT', { keyType: isTag ? 'tag' : 'key', key: hashedQuery, status: 'SAVED', expires: new Date(Date.now() + ttl * 1000).toISOString() });
         for (const table of tables) {
             const keys = this.usedTablesPerKey[table];
             if (keys === undefined) {
@@ -188,20 +204,12 @@ export class SQLCache extends DrizzleCache {
         }
         if (keysToDelete.size > 0 || tagsArray.length > 0) {
             for (const tag of tagsArray) {
-                await this.cache
-                    .then(async (cache) => cache.delete(this.getCacheKey({ tag })))
-                    .then(() => {
-                    if (this.logging)
-                        console.debug('SQLCache.delete', 'tag', tag, 'SUCCESS');
-                });
+                const deleted = await this.cache.then(async (cache) => cache.delete(this.getCacheKey({ tag })));
+                this.log('DELETE', { keyType: 'tag', key: tag, status: deleted ? 'DELETED' : 'NOT_FOUND', reason: 'Invalidated by tag on mutation' });
             }
             for (const key of keysToDelete) {
-                await this.cache
-                    .then(async (cache) => cache.delete(this.getCacheKey({ key })))
-                    .then(() => {
-                    if (this.logging)
-                        console.debug('SQLCache.delete', 'key', key, 'SUCCESS');
-                });
+                const deleted = await this.cache.then(async (cache) => cache.delete(this.getCacheKey({ key })));
+                this.log('DELETE', { keyType: 'key', key, status: deleted ? 'DELETED' : 'NOT_FOUND', reason: 'Invalidated by affected table on mutation' });
                 for (const table of tablesArray) {
                     const tableName = is(table, Table) ? getTableName(table) : table;
                     this.usedTablesPerKey[tableName] = [];

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 export * from './buffers.mjs';
 export * from './common.mjs';
 export * from './crypto.mjs';
-export * from './db.mjs';
 export * from './discord.mjs';
 export * from './dns.mjs';
 export * from './net.mjs';

package/dist/index.mjs

@@ -1,7 +1,6 @@
 export * from './buffers.mjs';
 export * from './common.mjs';
 export * from './crypto.mjs';
-export * from './db.mjs';
 export * from './discord.mjs';
 export * from './dns.mjs';
 export * from './net.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chainfuse/helpers",
-	"version": "4.4.8",
+	"version": "4.5.0",
 	"description": "",
 	"author": "ChainFuse",
 	"homepage": "https://github.com/ChainFuse/packages/tree/main/packages/helpers#readme",
@@ -80,7 +80,7 @@
 	},
 	"prettier": "@demosjarco/prettier-config",
 	"dependencies": {
-		"@chainfuse/types": "^4.2.22",
+		"@chainfuse/types": "^4.2.23",
 		"@discordjs/rest": "^2.6.1",
 		"chalk": "^5.6.2",
 		"cloudflare": "^5.2.0",
@@ -91,8 +91,8 @@
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@cloudflare/workers-types": "^4.20260405.1",
+		"@cloudflare/workers-types": "^4.20260414.1",
 		"@types/dns-packet": "^5.6.5"
 	},
-	"gitHead": "b0bcea1728f8c8e629219b670d3778dbe2cb4aae"
+	"gitHead": "87a45416de45d6efef0c4a107fec5de29329b45e"
 }