nextjs-dynamodb-cache 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sufyan Osamah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# nextjs-dynamodb-cache
+
+Drop-in [Next.js CacheHandler](https://nextjs.org/docs/app/api-reference/next-config-js/cacheHandler) that stores ISR cache and tag-based revalidation in DynamoDB.
+
+Built for Next.js deployments on **AWS Amplify, Lambda, App Runner, ECS**, or anywhere your filesystem is ephemeral — so your ISR cache and `revalidateTag()` calls actually survive deploys and work across instances.
+
+```
+npm install nextjs-dynamodb-cache
+```
+
+## Why
+
+The default Next.js cache handler writes to disk. On Amplify/Lambda/Fargate that means:
+
+- ISR pages re-render from scratch after every deploy
+- `revalidateTag()` only invalidates the instance that received the call
+- Multiple instances serve inconsistent stale content
+
+This package replaces the filesystem cache with DynamoDB. Cache entries are shared across all instances and survive deploys. Tag revalidation uses a GSI so it's a single query, not a full-table scan.
+
+## Quick start
+
+### 1. Create the DynamoDB table
+
+```bash
+npx nextjs-dynamodb-cache-create-table --table my-app-cache --region eu-central-1
+```
+
+This is idempotent. It creates the table, the `tag-index` GSI, and enables TTL on `expiresAt`. PAY_PER_REQUEST billing by default.
+
+Or programmatically:
+
+```ts
+import { createCacheTable } from "nextjs-dynamodb-cache/create-table";
+
+await createCacheTable({ tableName: "my-app-cache", region: "eu-central-1" });
+```
+
+### 2. Register the handler
+
+```js
+// next.config.js
+module.exports = {
+  cacheHandler: require.resolve("./cache-handler.mjs"),
+  cacheMaxMemorySize: 0, // disable in-memory cache so DDB is authoritative
+};
+```
+
+```js
+// cache-handler.mjs
+import { DynamoDBCacheHandler } from "nextjs-dynamodb-cache";
+
+export default DynamoDBCacheHandler.configure({
+  tableName: "my-app-cache",
+  region: "eu-central-1",
+  // optional: defaultTtlSeconds, keyPrefix, log, credentials
+});
+```
+
+That's it. `revalidateTag()` and `revalidatePath()` now work cluster-wide.
+
+## IAM
+
+The Lambda/Amplify role needs:
+
+```json
+{
+  "Effect": "Allow",
+  "Action": [
+    "dynamodb:GetItem",
+    "dynamodb:PutItem",
+    "dynamodb:DeleteItem",
+    "dynamodb:Query",
+    "dynamodb:BatchWriteItem"
+  ],
+  "Resource": [
+    "arn:aws:dynamodb:eu-central-1:*:table/my-app-cache",
+    "arn:aws:dynamodb:eu-central-1:*:table/my-app-cache/index/*"
+  ]
+}
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `tableName` | env `NEXT_CACHE_DYNAMODB_TABLE` or `nextjs-cache` | DynamoDB table name |
+| `region` | env `NEXT_CACHE_AWS_REGION` / `AWS_REGION` / `eu-central-1` | AWS region |
+| `credentials` | default chain | Explicit AWS credentials |
+| `tagIndexName` | `tag-index` | GSI name used for `revalidateTag` |
+| `defaultTtlSeconds` | `604800` (7 days) | TTL when Next.js omits `revalidate` |
+| `keyPrefix` | `""` | Prefix for keys (multi-app table sharing) |
+| `log` | `true` | Verbose logs on errors and revalidations |
+
+## How it works
+
+- **Schema:** single table, partition key `key`. Each entry has `value`, `expiresAt` (TTL), and optional `tags`.
+- **Tags:** for each tag a sentinel row `__tag__<tag>__<key>` is written. `revalidateTag(t)` queries the `tag-index` GSI on `tag = t`, collects the original cache keys, and batch-deletes them.
+- **TTL:** DynamoDB native TTL on `expiresAt` cleans up stale entries automatically — no cron required.
+- **Resilience:** every operation is wrapped in try/catch; a DynamoDB outage degrades to "cache miss," never a 500.
+
+## Status
+
+Battle-tested in production on Next.js 16 + Amplify hosting on the HonestDog marketplace. Compatible with Next.js 14, 15, and 16 cache-handler APIs.
+
+## License
+
+MIT

package/dist/chunk-BX5KU2C7.js

@@ -0,0 +1,59 @@
+// src/create-table.ts
+import {
+  CreateTableCommand,
+  DescribeTableCommand,
+  DynamoDBClient,
+  ResourceInUseException,
+  UpdateTimeToLiveCommand
+} from "@aws-sdk/client-dynamodb";
+async function createCacheTable(options) {
+  const region = options.region ?? process.env.AWS_REGION ?? "eu-central-1";
+  const tagIndexName = options.tagIndexName ?? "tag-index";
+  const billingMode = options.billingMode ?? "PAY_PER_REQUEST";
+  const client = new DynamoDBClient({
+    region,
+    ...options.credentials ? { credentials: options.credentials } : {}
+  });
+  try {
+    await client.send(
+      new CreateTableCommand({
+        TableName: options.tableName,
+        BillingMode: billingMode,
+        AttributeDefinitions: [
+          { AttributeName: "key", AttributeType: "S" },
+          { AttributeName: "tag", AttributeType: "S" }
+        ],
+        KeySchema: [{ AttributeName: "key", KeyType: "HASH" }],
+        GlobalSecondaryIndexes: [
+          {
+            IndexName: tagIndexName,
+            KeySchema: [{ AttributeName: "tag", KeyType: "HASH" }],
+            Projection: { ProjectionType: "ALL" }
+          }
+        ]
+      })
+    );
+  } catch (error) {
+    if (error instanceof ResourceInUseException) {
+      return { created: false };
+    }
+    throw error;
+  }
+  for (let i = 0; i < 60; i++) {
+    const status = await client.send(new DescribeTableCommand({ TableName: options.tableName })).then((r) => r.Table?.TableStatus);
+    if (status === "ACTIVE") break;
+    await new Promise((r) => setTimeout(r, 2e3));
+  }
+  await client.send(
+    new UpdateTimeToLiveCommand({
+      TableName: options.tableName,
+      TimeToLiveSpecification: { AttributeName: "expiresAt", Enabled: true }
+    })
+  );
+  return { created: true };
+}
+
+export {
+  createCacheTable
+};
+//# sourceMappingURL=chunk-BX5KU2C7.js.map

package/dist/chunk-BX5KU2C7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/create-table.ts"],"sourcesContent":["import {\n  CreateTableCommand,\n  DescribeTableCommand,\n  DynamoDBClient,\n  ResourceInUseException,\n  UpdateTimeToLiveCommand,\n  type DynamoDBClientConfig,\n} from \"@aws-sdk/client-dynamodb\";\n\nexport interface CreateTableOptions {\n  tableName: string;\n  region?: string;\n  credentials?: DynamoDBClientConfig[\"credentials\"];\n  /** GSI name for tag lookups. Defaults to `tag-index`. */\n  tagIndexName?: string;\n  /** Billing mode. Defaults to PAY_PER_REQUEST (recommended). */\n  billingMode?: \"PAY_PER_REQUEST\" | \"PROVISIONED\";\n}\n\n/**\n * Idempotently create the DynamoDB table required by `nextjs-dynamodb-cache`.\n *\n * Schema:\n *   - Partition key: `key` (S)\n *   - GSI `tag-index`: partition key `tag` (S)\n *   - TTL attribute: `expiresAt` (unix seconds)\n */\nexport async function createCacheTable(options: CreateTableOptions): Promise<{ created: boolean }> {\n  const region = options.region ?? process.env.AWS_REGION ?? \"eu-central-1\";\n  const tagIndexName = options.tagIndexName ?? \"tag-index\";\n  const billingMode = options.billingMode ?? \"PAY_PER_REQUEST\";\n\n  const client = new DynamoDBClient({\n    region,\n    ...(options.credentials ? { credentials: options.credentials } : {}),\n  });\n\n  try {\n    await client.send(\n      new CreateTableCommand({\n        TableName: options.tableName,\n        BillingMode: billingMode,\n        AttributeDefinitions: [\n          { AttributeName: \"key\", AttributeType: \"S\" },\n          { AttributeName: \"tag\", AttributeType: \"S\" },\n        ],\n        KeySchema: [{ AttributeName: \"key\", KeyType: \"HASH\" }],\n        GlobalSecondaryIndexes: [\n          {\n            IndexName: tagIndexName,\n            KeySchema: [{ AttributeName: \"tag\", KeyType: \"HASH\" }],\n            Projection: { ProjectionType: \"ALL\" },\n          },\n        ],\n      }),\n    );\n  } catch (error) {\n    if (error instanceof ResourceInUseException) {\n      return { created: false };\n    }\n    throw error;\n  }\n\n  // Wait until ACTIVE so we can enable TTL.\n  for (let i = 0; i < 60; i++) {\n    const status = await client\n      .send(new DescribeTableCommand({ TableName: options.tableName }))\n      .then((r) => r.Table?.TableStatus);\n    if (status === \"ACTIVE\") break;\n    await new Promise((r) => setTimeout(r, 2000));\n  }\n\n  await client.send(\n    new UpdateTimeToLiveCommand({\n      TableName: options.tableName,\n      TimeToLiveSpecification: { AttributeName: \"expiresAt\", Enabled: true },\n    }),\n  );\n\n  return { created: true };\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAoBP,eAAsB,iBAAiB,SAA4D;AACjG,QAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI,cAAc;AAC3D,QAAM,eAAe,QAAQ,gBAAgB;AAC7C,QAAM,cAAc,QAAQ,eAAe;AAE3C,QAAM,SAAS,IAAI,eAAe;AAAA,IAChC;AAAA,IACA,GAAI,QAAQ,cAAc,EAAE,aAAa,QAAQ,YAAY,IAAI,CAAC;AAAA,EACpE,CAAC;AAED,MAAI;AACF,UAAM,OAAO;AAAA,MACX,IAAI,mBAAmB;AAAA,QACrB,WAAW,QAAQ;AAAA,QACnB,aAAa;AAAA,QACb,sBAAsB;AAAA,UACpB,EAAE,eAAe,OAAO,eAAe,IAAI;AAAA,UAC3C,EAAE,eAAe,OAAO,eAAe,IAAI;AAAA,QAC7C;AAAA,QACA,WAAW,CAAC,EAAE,eAAe,OAAO,SAAS,OAAO,CAAC;AAAA,QACrD,wBAAwB;AAAA,UACtB;AAAA,YACE,WAAW;AAAA,YACX,WAAW,CAAC,EAAE,eAAe,OAAO,SAAS,OAAO,CAAC;AAAA,YACrD,YAAY,EAAE,gBAAgB,MAAM;AAAA,UACtC;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,SAAS,OAAO;AACd,QAAI,iBAAiB,wBAAwB;AAC3C,aAAO,EAAE,SAAS,MAAM;AAAA,IAC1B;AACA,UAAM;AAAA,EACR;AAGA,WAAS,IAAI,GAAG,IAAI,IAAI,KAAK;AAC3B,UAAM,SAAS,MAAM,OAClB,KAAK,IAAI,qBAAqB,EAAE,WAAW,QAAQ,UAAU,CAAC,CAAC,EAC/D,KAAK,CAAC,MAAM,EAAE,OAAO,WAAW;AACnC,QAAI,WAAW,SAAU;AACzB,UAAM,IAAI,QAAQ,CAAC,MAAM,WAAW,GAAG,GAAI,CAAC;AAAA,EAC9C;AAEA,QAAM,OAAO;AAAA,IACX,IAAI,wBAAwB;AAAA,MAC1B,WAAW,QAAQ;AAAA,MACnB,yBAAyB,EAAE,eAAe,aAAa,SAAS,KAAK;AAAA,IACvE,CAAC;AAAA,EACH;AAEA,SAAO,EAAE,SAAS,KAAK;AACzB;","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import {
+  createCacheTable
+} from "./chunk-BX5KU2C7.js";
+
+// src/cli.ts
+function arg(flag) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 ? process.argv[i + 1] : void 0;
+}
+async function main() {
+  const tableName = arg("--table") ?? process.env.NEXT_CACHE_DYNAMODB_TABLE;
+  if (!tableName) {
+    console.error("usage: nextjs-dynamodb-cache-create-table --table <name> [--region <region>]");
+    process.exit(1);
+  }
+  const region = arg("--region");
+  const result = await createCacheTable({ tableName, ...region ? { region } : {} });
+  console.log(result.created ? `Created table ${tableName}.` : `Table ${tableName} already exists.`);
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { createCacheTable } from \"./create-table.js\";\n\nfunction arg(flag: string): string | undefined {\n  const i = process.argv.indexOf(flag);\n  return i >= 0 ? process.argv[i + 1] : undefined;\n}\n\nasync function main(): Promise<void> {\n  const tableName = arg(\"--table\") ?? process.env.NEXT_CACHE_DYNAMODB_TABLE;\n  if (!tableName) {\n    console.error(\"usage: nextjs-dynamodb-cache-create-table --table <name> [--region <region>]\");\n    process.exit(1);\n  }\n  const region = arg(\"--region\");\n  const result = await createCacheTable({ tableName, ...(region ? { region } : {}) });\n  console.log(result.created ? `Created table ${tableName}.` : `Table ${tableName} already exists.`);\n}\n\nmain().catch((err) => {\n  console.error(err);\n  process.exit(1);\n});\n"],"mappings":";;;;;;AAGA,SAAS,IAAI,MAAkC;AAC7C,QAAM,IAAI,QAAQ,KAAK,QAAQ,IAAI;AACnC,SAAO,KAAK,IAAI,QAAQ,KAAK,IAAI,CAAC,IAAI;AACxC;AAEA,eAAe,OAAsB;AACnC,QAAM,YAAY,IAAI,SAAS,KAAK,QAAQ,IAAI;AAChD,MAAI,CAAC,WAAW;AACd,YAAQ,MAAM,8EAA8E;AAC5F,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,QAAM,SAAS,IAAI,UAAU;AAC7B,QAAM,SAAS,MAAM,iBAAiB,EAAE,WAAW,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC,EAAG,CAAC;AAClF,UAAQ,IAAI,OAAO,UAAU,iBAAiB,SAAS,MAAM,SAAS,SAAS,kBAAkB;AACnG;AAEA,KAAK,EAAE,MAAM,CAAC,QAAQ;AACpB,UAAQ,MAAM,GAAG;AACjB,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/dist/create-table.d.ts

@@ -0,0 +1,24 @@
+import { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+
+interface CreateTableOptions {
+    tableName: string;
+    region?: string;
+    credentials?: DynamoDBClientConfig["credentials"];
+    /** GSI name for tag lookups. Defaults to `tag-index`. */
+    tagIndexName?: string;
+    /** Billing mode. Defaults to PAY_PER_REQUEST (recommended). */
+    billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
+}
+/**
+ * Idempotently create the DynamoDB table required by `nextjs-dynamodb-cache`.
+ *
+ * Schema:
+ *   - Partition key: `key` (S)
+ *   - GSI `tag-index`: partition key `tag` (S)
+ *   - TTL attribute: `expiresAt` (unix seconds)
+ */
+declare function createCacheTable(options: CreateTableOptions): Promise<{
+    created: boolean;
+}>;
+
+export { type CreateTableOptions, createCacheTable };

package/dist/create-table.js

@@ -0,0 +1,7 @@
+import {
+  createCacheTable
+} from "./chunk-BX5KU2C7.js";
+export {
+  createCacheTable
+};
+//# sourceMappingURL=create-table.js.map

package/dist/create-table.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+
+interface DynamoDBCacheOptions {
+    /** DynamoDB table name. Defaults to env `NEXT_CACHE_DYNAMODB_TABLE` or `nextjs-cache`. */
+    tableName?: string;
+    /** AWS region. Defaults to env `NEXT_CACHE_AWS_REGION` / `AWS_REGION` / `eu-central-1`. */
+    region?: string;
+    /** Optional explicit credentials. Otherwise the default AWS credential chain is used. */
+    credentials?: DynamoDBClientConfig["credentials"];
+    /** Name of the GSI used for tag-based revalidation. Defaults to `tag-index`. */
+    tagIndexName?: string;
+    /** Default TTL in seconds when the Next.js context omits `revalidate`. Defaults to 7 days. */
+    defaultTtlSeconds?: number;
+    /** Optional prefix added to every DynamoDB key (useful when sharing a table across apps). */
+    keyPrefix?: string;
+    /** Set to false to disable verbose logs. Defaults to true. */
+    log?: boolean;
+}
+interface NextCacheContext {
+    revalidate?: number | false;
+    tags?: string[];
+}
+/**
+ * Next.js CacheHandler backed by DynamoDB.
+ *
+ * Register it in `next.config.js`:
+ *
+ * ```js
+ * // next.config.js
+ * module.exports = {
+ *   cacheHandler: require.resolve("./cache-handler.mjs"),
+ *   cacheMaxMemorySize: 0,
+ * };
+ *
+ * // cache-handler.mjs
+ * import { DynamoDBCacheHandler } from "nextjs-dynamodb-cache";
+ * export default DynamoDBCacheHandler;
+ * ```
+ */
+declare class DynamoDBCacheHandler {
+    private readonly tableName;
+    private readonly region;
+    private readonly tagIndexName;
+    private readonly defaultTtlSeconds;
+    private readonly keyPrefix;
+    private readonly log;
+    private readonly credentials?;
+    private docClient;
+    constructor(_nextOptions?: unknown);
+    /**
+     * Configure the handler globally before Next.js instantiates it.
+     * Call this from your `cache-handler.mjs` entrypoint.
+     */
+    static globalConfig: DynamoDBCacheOptions | null;
+    static configure(options: DynamoDBCacheOptions): typeof DynamoDBCacheHandler;
+    private getClient;
+    private k;
+    get(rawKey: string): Promise<unknown | null>;
+    set(rawKey: string, data: unknown, ctx?: NextCacheContext): Promise<void>;
+    revalidateTag(tag: string): Promise<void>;
+    /** Manual deletion of a single key. Not called by Next.js but useful for ops scripts. */
+    delete(rawKey: string): Promise<void>;
+    private warn;
+}
+
+export { DynamoDBCacheHandler, type DynamoDBCacheOptions, DynamoDBCacheHandler as default };

package/dist/index.js

@@ -0,0 +1,161 @@
+// src/index.ts
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import {
+  BatchWriteCommand,
+  DeleteCommand,
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  QueryCommand
+} from "@aws-sdk/lib-dynamodb";
+var DynamoDBCacheHandler = class _DynamoDBCacheHandler {
+  tableName;
+  region;
+  tagIndexName;
+  defaultTtlSeconds;
+  keyPrefix;
+  log;
+  credentials;
+  docClient = null;
+  // Next.js instantiates the handler with its own options bag; we accept and ignore it.
+  // Library users configure via the static `configure()` helper or env vars.
+  constructor(_nextOptions) {
+    const cfg = _DynamoDBCacheHandler.globalConfig ?? {};
+    this.tableName = cfg.tableName ?? process.env.NEXT_CACHE_DYNAMODB_TABLE ?? "nextjs-cache";
+    this.region = cfg.region ?? process.env.NEXT_CACHE_AWS_REGION ?? process.env.AWS_REGION ?? "eu-central-1";
+    this.tagIndexName = cfg.tagIndexName ?? "tag-index";
+    this.defaultTtlSeconds = cfg.defaultTtlSeconds ?? 7 * 24 * 60 * 60;
+    this.keyPrefix = cfg.keyPrefix ?? "";
+    this.log = cfg.log ?? true;
+    this.credentials = cfg.credentials;
+  }
+  /**
+   * Configure the handler globally before Next.js instantiates it.
+   * Call this from your `cache-handler.mjs` entrypoint.
+   */
+  static globalConfig = null;
+  static configure(options) {
+    _DynamoDBCacheHandler.globalConfig = options;
+    return _DynamoDBCacheHandler;
+  }
+  getClient() {
+    if (!this.docClient) {
+      const config = { region: this.region };
+      if (this.credentials) config.credentials = this.credentials;
+      this.docClient = DynamoDBDocumentClient.from(new DynamoDBClient(config), {
+        marshallOptions: { removeUndefinedValues: true }
+      });
+    }
+    return this.docClient;
+  }
+  k(key) {
+    return this.keyPrefix ? `${this.keyPrefix}${key}` : key;
+  }
+  async get(rawKey) {
+    const key = this.k(rawKey);
+    try {
+      const result = await this.getClient().send(
+        new GetCommand({ TableName: this.tableName, Key: { key } })
+      );
+      const item = result.Item;
+      if (!item) return null;
+      if (item.expiresAt && item.expiresAt < Math.floor(Date.now() / 1e3)) return null;
+      return item.value;
+    } catch (error) {
+      this.warn("get", error);
+      return null;
+    }
+  }
+  async set(rawKey, data, ctx) {
+    const key = this.k(rawKey);
+    try {
+      const now = Math.floor(Date.now() / 1e3);
+      const ttl = typeof ctx?.revalidate === "number" && ctx.revalidate > 0 ? ctx.revalidate : this.defaultTtlSeconds;
+      const expiresAt = now + ttl;
+      const tags = ctx?.tags ?? [];
+      const item = {
+        key,
+        value: data,
+        createdAt: now,
+        expiresAt,
+        tags: tags.length > 0 ? tags : void 0,
+        tag: tags[0]
+      };
+      await this.getClient().send(new PutCommand({ TableName: this.tableName, Item: item }));
+      if (tags.length > 0) {
+        const mappings = tags.map((t) => ({
+          PutRequest: {
+            Item: { key: this.k(`__tag__${t}__${rawKey}`), cacheKey: key, tag: t, expiresAt }
+          }
+        }));
+        for (let i = 0; i < mappings.length; i += 25) {
+          await this.getClient().send(
+            new BatchWriteCommand({
+              RequestItems: { [this.tableName]: mappings.slice(i, i + 25) }
+            })
+          );
+        }
+      }
+    } catch (error) {
+      this.warn("set", error);
+    }
+  }
+  async revalidateTag(tag) {
+    try {
+      const result = await this.getClient().send(
+        new QueryCommand({
+          TableName: this.tableName,
+          IndexName: this.tagIndexName,
+          KeyConditionExpression: "tag = :tag",
+          ExpressionAttributeValues: { ":tag": tag }
+        })
+      );
+      const items = result.Items ?? [];
+      if (items.length === 0) return;
+      const keysToDelete = /* @__PURE__ */ new Set();
+      for (const item of items) {
+        const cacheKey = item.cacheKey ?? item.key;
+        if (cacheKey && !cacheKey.includes("__tag__")) keysToDelete.add(cacheKey);
+        keysToDelete.add(item.key);
+      }
+      const deleteRequests = Array.from(keysToDelete).map((k) => ({
+        DeleteRequest: { Key: { key: k } }
+      }));
+      for (let i = 0; i < deleteRequests.length; i += 25) {
+        await this.getClient().send(
+          new BatchWriteCommand({
+            RequestItems: { [this.tableName]: deleteRequests.slice(i, i + 25) }
+          })
+        );
+      }
+      if (this.log) {
+        console.log(
+          `[nextjs-dynamodb-cache] revalidated tag "${tag}" (${keysToDelete.size} keys)`
+        );
+      }
+    } catch (error) {
+      this.warn("revalidateTag", error);
+    }
+  }
+  /** Manual deletion of a single key. Not called by Next.js but useful for ops scripts. */
+  async delete(rawKey) {
+    try {
+      await this.getClient().send(
+        new DeleteCommand({ TableName: this.tableName, Key: { key: this.k(rawKey) } })
+      );
+    } catch (error) {
+      this.warn("delete", error);
+    }
+  }
+  warn(op, error) {
+    if (!this.log) return;
+    const msg = error instanceof Error ? error.message : String(error);
+    console.warn(`[nextjs-dynamodb-cache] ${op} failed: ${msg}`);
+  }
+};
+var index_default = DynamoDBCacheHandler;
+export {
+  DynamoDBCacheHandler,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { DynamoDBClient, type DynamoDBClientConfig } from \"@aws-sdk/client-dynamodb\";\nimport {\n  BatchWriteCommand,\n  DeleteCommand,\n  DynamoDBDocumentClient,\n  GetCommand,\n  PutCommand,\n  QueryCommand,\n} from \"@aws-sdk/lib-dynamodb\";\n\nexport interface DynamoDBCacheOptions {\n  /** DynamoDB table name. Defaults to env `NEXT_CACHE_DYNAMODB_TABLE` or `nextjs-cache`. */\n  tableName?: string;\n  /** AWS region. Defaults to env `NEXT_CACHE_AWS_REGION` / `AWS_REGION` / `eu-central-1`. */\n  region?: string;\n  /** Optional explicit credentials. Otherwise the default AWS credential chain is used. */\n  credentials?: DynamoDBClientConfig[\"credentials\"];\n  /** Name of the GSI used for tag-based revalidation. Defaults to `tag-index`. */\n  tagIndexName?: string;\n  /** Default TTL in seconds when the Next.js context omits `revalidate`. Defaults to 7 days. */\n  defaultTtlSeconds?: number;\n  /** Optional prefix added to every DynamoDB key (useful when sharing a table across apps). */\n  keyPrefix?: string;\n  /** Set to false to disable verbose logs. Defaults to true. */\n  log?: boolean;\n}\n\ninterface NextCacheContext {\n  revalidate?: number | false;\n  tags?: string[];\n}\n\ninterface CachedItem {\n  key: string;\n  value: unknown;\n  createdAt: number;\n  expiresAt: number;\n  tags?: string[];\n  tag?: string;\n  cacheKey?: string;\n}\n\n/**\n * Next.js CacheHandler backed by DynamoDB.\n *\n * Register it in `next.config.js`:\n *\n * ```js\n * // next.config.js\n * module.exports = {\n *   cacheHandler: require.resolve(\"./cache-handler.mjs\"),\n *   cacheMaxMemorySize: 0,\n * };\n *\n * // cache-handler.mjs\n * import { DynamoDBCacheHandler } from \"nextjs-dynamodb-cache\";\n * export default DynamoDBCacheHandler;\n * ```\n */\nexport class DynamoDBCacheHandler {\n  private readonly tableName: string;\n  private readonly region: string;\n  private readonly tagIndexName: string;\n  private readonly defaultTtlSeconds: number;\n  private readonly keyPrefix: string;\n  private readonly log: boolean;\n  private readonly credentials?: DynamoDBClientConfig[\"credentials\"];\n  private docClient: DynamoDBDocumentClient | null = null;\n\n  // Next.js instantiates the handler with its own options bag; we accept and ignore it.\n  // Library users configure via the static `configure()` helper or env vars.\n  constructor(_nextOptions?: unknown) {\n    const cfg = DynamoDBCacheHandler.globalConfig ?? {};\n    this.tableName = cfg.tableName ?? process.env.NEXT_CACHE_DYNAMODB_TABLE ?? \"nextjs-cache\";\n    this.region =\n      cfg.region ??\n      process.env.NEXT_CACHE_AWS_REGION ??\n      process.env.AWS_REGION ??\n      \"eu-central-1\";\n    this.tagIndexName = cfg.tagIndexName ?? \"tag-index\";\n    this.defaultTtlSeconds = cfg.defaultTtlSeconds ?? 7 * 24 * 60 * 60;\n    this.keyPrefix = cfg.keyPrefix ?? \"\";\n    this.log = cfg.log ?? true;\n    this.credentials = cfg.credentials;\n  }\n\n  /**\n   * Configure the handler globally before Next.js instantiates it.\n   * Call this from your `cache-handler.mjs` entrypoint.\n   */\n  static globalConfig: DynamoDBCacheOptions | null = null;\n  static configure(options: DynamoDBCacheOptions): typeof DynamoDBCacheHandler {\n    DynamoDBCacheHandler.globalConfig = options;\n    return DynamoDBCacheHandler;\n  }\n\n  private getClient(): DynamoDBDocumentClient {\n    if (!this.docClient) {\n      const config: DynamoDBClientConfig = { region: this.region };\n      if (this.credentials) config.credentials = this.credentials;\n      this.docClient = DynamoDBDocumentClient.from(new DynamoDBClient(config), {\n        marshallOptions: { removeUndefinedValues: true },\n      });\n    }\n    return this.docClient;\n  }\n\n  private k(key: string): string {\n    return this.keyPrefix ? `${this.keyPrefix}${key}` : key;\n  }\n\n  async get(rawKey: string): Promise<unknown | null> {\n    const key = this.k(rawKey);\n    try {\n      const result = await this.getClient().send(\n        new GetCommand({ TableName: this.tableName, Key: { key } }),\n      );\n      const item = result.Item as CachedItem | undefined;\n      if (!item) return null;\n      if (item.expiresAt && item.expiresAt < Math.floor(Date.now() / 1000)) return null;\n      return item.value;\n    } catch (error) {\n      this.warn(\"get\", error);\n      return null;\n    }\n  }\n\n  async set(rawKey: string, data: unknown, ctx?: NextCacheContext): Promise<void> {\n    const key = this.k(rawKey);\n    try {\n      const now = Math.floor(Date.now() / 1000);\n      const ttl =\n        typeof ctx?.revalidate === \"number\" && ctx.revalidate > 0\n          ? ctx.revalidate\n          : this.defaultTtlSeconds;\n      const expiresAt = now + ttl;\n      const tags = ctx?.tags ?? [];\n\n      const item: CachedItem = {\n        key,\n        value: data,\n        createdAt: now,\n        expiresAt,\n        tags: tags.length > 0 ? tags : undefined,\n        tag: tags[0],\n      };\n\n      await this.getClient().send(new PutCommand({ TableName: this.tableName, Item: item }));\n\n      if (tags.length > 0) {\n        const mappings = tags.map((t) => ({\n          PutRequest: {\n            Item: { key: this.k(`__tag__${t}__${rawKey}`), cacheKey: key, tag: t, expiresAt },\n          },\n        }));\n        for (let i = 0; i < mappings.length; i += 25) {\n          await this.getClient().send(\n            new BatchWriteCommand({\n              RequestItems: { [this.tableName]: mappings.slice(i, i + 25) },\n            }),\n          );\n        }\n      }\n    } catch (error) {\n      this.warn(\"set\", error);\n    }\n  }\n\n  async revalidateTag(tag: string): Promise<void> {\n    try {\n      const result = await this.getClient().send(\n        new QueryCommand({\n          TableName: this.tableName,\n          IndexName: this.tagIndexName,\n          KeyConditionExpression: \"tag = :tag\",\n          ExpressionAttributeValues: { \":tag\": tag },\n        }),\n      );\n\n      const items = (result.Items as CachedItem[] | undefined) ?? [];\n      if (items.length === 0) return;\n\n      const keysToDelete = new Set<string>();\n      for (const item of items) {\n        const cacheKey = item.cacheKey ?? item.key;\n        if (cacheKey && !cacheKey.includes(\"__tag__\")) keysToDelete.add(cacheKey);\n        keysToDelete.add(item.key);\n      }\n\n      const deleteRequests = Array.from(keysToDelete).map((k) => ({\n        DeleteRequest: { Key: { key: k } },\n      }));\n      for (let i = 0; i < deleteRequests.length; i += 25) {\n        await this.getClient().send(\n          new BatchWriteCommand({\n            RequestItems: { [this.tableName]: deleteRequests.slice(i, i + 25) },\n          }),\n        );\n      }\n\n      if (this.log) {\n        console.log(\n          `[nextjs-dynamodb-cache] revalidated tag \"${tag}\" (${keysToDelete.size} keys)`,\n        );\n      }\n    } catch (error) {\n      this.warn(\"revalidateTag\", error);\n    }\n  }\n\n  /** Manual deletion of a single key. Not called by Next.js but useful for ops scripts. */\n  async delete(rawKey: string): Promise<void> {\n    try {\n      await this.getClient().send(\n        new DeleteCommand({ TableName: this.tableName, Key: { key: this.k(rawKey) } }),\n      );\n    } catch (error) {\n      this.warn(\"delete\", error);\n    }\n  }\n\n  private warn(op: string, error: unknown): void {\n    if (!this.log) return;\n    const msg = error instanceof Error ? error.message : String(error);\n    console.warn(`[nextjs-dynamodb-cache] ${op} failed: ${msg}`);\n  }\n}\n\nexport default DynamoDBCacheHandler;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "nextjs-dynamodb-cache",
+  "version": "0.1.0",
+  "description": "Drop-in Next.js 14/15/16 CacheHandler that stores ISR cache and tag revalidation in DynamoDB. Survives deploys on AWS Amplify, Lambda, App Runner, and other ephemeral runtimes.",
+  "keywords": [
+    "nextjs",
+    "next.js",
+    "isr",
+    "cache",
+    "cache-handler",
+    "dynamodb",
+    "aws",
+    "amplify",
+    "lambda",
+    "revalidate",
+    "revalidatetag"
+  ],
+  "license": "MIT",
+  "author": "Sufyan Osamah",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sufyman/nextjs-dynamodb-cache"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./create-table": {
+      "types": "./dist/create-table.d.ts",
+      "import": "./dist/create-table.js"
+    }
+  },
+  "bin": {
+    "nextjs-dynamodb-cache-create-table": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.600.0",
+    "@aws-sdk/lib-dynamodb": "^3.600.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "aws-sdk-client-mock": "^4.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}