Add support for ES Modules (#276)

.changeset/tough-moles-sing.md

@@ -0,0 +1,5 @@
+---
+'cache-handler-docs': patch
+---
+
+Added a section with ES Modules example.

.changeset/wicked-games-switch.md

@@ -0,0 +1,5 @@
+---
+'@neshca/cache-handler': patch
+---
+
+Added support for ES Modules.

.github/workflows/tests.yml

@@ -10,7 +10,7 @@ jobs:
     timeout-minutes: 10
     runs-on: ubuntu-latest
     env:
-      HANDLER_PATH: ./cache-handler-redis-stack
+      HANDLER_PATH: ./cache-handler-redis-stack.mjs
       REDIS_URL: redis://localhost:6379
     services:
       redis:

apps/cache-testing/cache-handler-local.mjs

@@ -0,0 +1,13 @@
+import { IncrementalCache } from '@neshca/cache-handler';
+import createLruCache from '@neshca/cache-handler/local-lru';
+
+IncrementalCache.onCreation(async () => {
+    const localCache = createLruCache();
+
+    return {
+        cache: localCache,
+        useFileSystem: true,
+    };
+});
+
+export default IncrementalCache;

apps/cache-testing/cache-handler-redis-stack.js → apps/cache-testing/cache-handler-redis-stack.mjs

@@ -1,8 +1,8 @@
-const { IncrementalCache } = require('@neshca/cache-handler');
-const createRedisCache = require('@neshca/cache-handler/redis-stack').default;
-const createRedisStringsCache = require('@neshca/cache-handler/redis-strings').default;
-const createLruCache = require('@neshca/cache-handler/local-lru').default;
-const { createClient } = require('redis');
+import { IncrementalCache } from '@neshca/cache-handler';
+import createLruCache from '@neshca/cache-handler/local-lru';
+import createRedisCache from '@neshca/cache-handler/redis-stack';
+import createRedisStringsCache from '@neshca/cache-handler/redis-strings';
+import { createClient } from 'redis';
 
 if (!process.env.REDIS_URL) {
     console.warn('Make sure that REDIS_URL is added to the .env.local file and loaded properly.');
@@ -38,4 +38,4 @@ IncrementalCache.onCreation(async () => {
     };
 });
 
-module.exports = IncrementalCache;
+export default IncrementalCache;

apps/cache-testing/cache-handler-redis-strings.js → apps/cache-testing/cache-handler-redis-strings.mjs

@@ -1,7 +1,7 @@
-const { IncrementalCache } = require('@neshca/cache-handler');
-const createRedisCache = require('@neshca/cache-handler/redis-strings').default;
-const createLruCache = require('@neshca/cache-handler/local-lru').default;
-const { createClient } = require('redis');
+import { IncrementalCache } from '@neshca/cache-handler';
+import createLruCache from '@neshca/cache-handler/local-lru';
+import createRedisCache from '@neshca/cache-handler/redis-strings';
+import { createClient } from 'redis';
 
 if (!process.env.REDIS_URL) {
     console.warn('Make sure that REDIS_URL is added to the .env.local file and loaded properly.');
@@ -36,4 +36,4 @@ IncrementalCache.onCreation(async () => {
     };
 });
 
-module.exports = IncrementalCache;
+export default IncrementalCache;

apps/cache-testing/cache-handler-server.mjs

@@ -0,0 +1,24 @@
+import Timers from 'node:timers/promises';
+
+import { IncrementalCache } from '@neshca/cache-handler';
+import createLruCache from '@neshca/cache-handler/local-lru';
+import createServerCache from '@neshca/cache-handler/server';
+
+const baseUrl = process.env.REMOTE_CACHE_SERVER_BASE_URL ?? 'http://localhost:8080';
+
+IncrementalCache.onCreation(async () => {
+    await Timers.scheduler.wait(1000);
+
+    const httpCache = createServerCache({
+        baseUrl,
+    });
+
+    const localCache = createLruCache();
+
+    return {
+        cache: [httpCache, localCache],
+        useFileSystem: true,
+    };
+});
+
+export default IncrementalCache;

apps/cache-testing/next.config.js

@@ -1,6 +1,6 @@
 const path = require('node:path');
 
-const cacheHandler = require.resolve(process.env.HANDLER_PATH ?? './cache-handler-redis-stack');
+const cacheHandler = require.resolve(process.env.HANDLER_PATH ?? './cache-handler-redis-stack.mjs');
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {

docs/cache-handler-docs/src/pages/configuration/development-environment.mdx

@@ -6,11 +6,11 @@ The easiest way to turn off the cache handler in a development environment is to
 
 ```js filename="next.config.js" copy
 const nextConfig = {
-    cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler') : undefined,
+    cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.js') : undefined,
     // Use `experimental` option instead of the `cacheHandler` property when using Next.js versions from 13.5.1 to 14.0.4
     /* experimental: {
             incrementalCacheHandlerPath:
-                process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler') : undefined,
+                process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.js') : undefined,
     }, */
 };
 ```

docs/cache-handler-docs/src/pages/installation.mdx

@@ -52,7 +52,7 @@ pnpm create next-app --example cache-handler-redis cache-handler-redis-app
     const { IncrementalCache } = require('@neshca/cache-handler');
 
     IncrementalCache.onCreation(async () => {
-        // Don't do this in production. This is just an example.
+        // Don't use Map in production. This is just an example.
         const cacheStore = new Map();
 
         const cache = {
@@ -73,16 +73,43 @@ pnpm create next-app --example cache-handler-redis cache-handler-redis-app
     module.exports = IncrementalCache;
     ```
 
+    EcmaScript modules can be used by adding the `.mjs` extension to the file and using an `import` statement instead of a `require` call:
+
+    ```js filename="cache-handler.mjs" copy
+    import { IncrementalCache } from '@neshca/cache-handler';
+
+    IncrementalCache.onCreation(async () => {
+        const cacheStore = new Map();
+
+        const cache = {
+            async get(key) {
+                return cacheStore.get(key);
+            },
+            async set(key, value) {
+                cacheStore.set(key, value);
+            },
+        };
+
+        return {
+            cache,
+            useFileSystem: true,
+        };
+    });
+
+    export default IncrementalCache;
+    ```
+
 3. **Integrate with Next.js**:  
    Update your `next.config.js` to utilize the cache handler, ensuring it's only active in production:
 
     ```js filename="next.config.js" copy
     const nextConfig = {
-        cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler') : undefined,
+        // './cache-handler.mjs' in case you're using EcmaScript modules.
+        cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.js') : undefined,
         // Use `experimental` option instead of the `cacheHandler` property when using Next.js versions from 13.5.1 to 14.0.4
         /* experimental: {
             incrementalCacheHandlerPath:
-                process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler') : undefined,
+                process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.js') : undefined,
         }, */
     };
 

packages/cache-handler/package.json

@@ -23,29 +23,38 @@
     },
     "type": "module",
     "exports": {
-        ".": "./dist/cache-handler.cjs",
-        "./helpers": "./dist/helpers/helpers.cjs",
-        "./*": "./dist/handlers/*.cjs"
+        ".": {
+            "require": "./dist/cache-handler.cjs",
+            "import": "./dist/cache-handler.js"
+        },
+        "./helpers": {
+            "require": "./dist/helpers/helpers.cjs",
+            "import": "./dist/helpers/helpers.js"
+        },
+        "./*": {
+            "require": "./dist/handlers/*.cjs",
+            "import": "./dist/handlers/*.js"
+        }
     },
     "typesVersions": {
         "*": {
             "*": [
-                "dist/cache-handler.d.cts"
+                "dist/cache-handler.d.ts"
             ],
             "helpers": [
-                "dist/helpers/helpers.d.cts"
+                "dist/helpers/helpers.d.ts"
             ],
             "redis-stack": [
-                "dist/handlers/redis-stack.d.cts"
+                "dist/handlers/redis-stack.d.ts"
             ],
             "redis-strings": [
-                "dist/handlers/redis-strings.d.cts"
+                "dist/handlers/redis-strings.d.ts"
             ],
             "server": [
-                "dist/handlers/server.d.cts"
+                "dist/handlers/server.d.ts"
             ],
             "local-lru": [
-                "dist/handlers/local-lru.d.cts"
+                "dist/handlers/local-lru.d.ts"
             ]
         }
     },

packages/cache-handler/tsup.config.ts

@@ -6,7 +6,7 @@ export const tsup = defineConfig({
     splitting: false,
     outDir: 'dist',
     clean: false,
-    format: ['cjs'],
+    format: ['cjs', 'esm'],
     dts: { resolve: true },
     target: 'node18',
     noExternal: ['@neshca/json-replacer-reviver', 'lru-cache'],