@keyv/dynamo 1.0.0 → 1.1.0

package/README.md

@@ -35,6 +35,88 @@ e.g:
 const keyv = new KeyvDynamo({ tableName: 'cacheTable' });
 ```
 
+### Accessing the DynamoDB Client
+
+The DynamoDB client is exposed as a property for advanced use cases:
+
+```js
+const store = new KeyvDynamo();
+const dynamoClient = store.client; // DynamoDBDocument instance
+
+// You can use the client directly for custom operations
+await dynamoClient.get({ TableName: 'keyv', Key: { id: 'myKey' } });
+```
+
+## Usage with NestJS
+
+Since DynamoDB has a 400KB limit per item, compressing data can help in some cases.
+
+### With a payload less than or equal to 400KB
+
+```js
+import { Keyv } from 'keyv'
+import { KeyvDynamo } from '@keyv/dynamo'
+import { DynamoModule } from '@lyfe/dynamo-module'
+import { CacheModule } from '@nestjs/cache-manager'
+import { Module } from '@nestjs/common'
+
+@Module({
+  imports: [
+    CacheModule.registerAsync({
+      isGlobal: true,
+      useFactory: async () => {
+        return {
+          stores: [
+            new Keyv({
+              store: new KeyvDynamo({
+                tableName: 'TableName',
+              }),
+            }),
+          ],
+        }
+      },
+    }),
+  ],
+  exports: [DynamoModule],
+})
+export class InfrastructureModule {}
+
+```
+
+### With a payload greater than 400KB
+
+```js
+import { Keyv } from 'keyv'
+import KeyvBrotli from '@keyv/compress-brotli'
+import { KeyvDynamo } from '@keyv/dynamo'
+import { DynamoModule } from '@lyfe/dynamo-module'
+import { CacheModule } from '@nestjs/cache-manager'
+import { Module } from '@nestjs/common'
+
+@Module({
+  imports: [
+    CacheModule.registerAsync({
+      isGlobal: true,
+      useFactory: async () => {
+        return {
+          stores: [
+            new Keyv({
+              store: new KeyvDynamo({
+                tableName: 'TableName',
+              }),
+              compression: new KeyvBrotli(),
+            }),
+          ],
+        }
+      },
+    }),
+  ],
+  exports: [DynamoModule],
+})
+export class InfrastructureModule {}
+
+```
+
 ## License
 
 [MIT © Jared Wray](LISCENCE)

package/dist/index.cjs

@@ -34,15 +34,16 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var import_events = __toESM(require("events"), 1);
+var import_node_events = __toESM(require("events"), 1);
 var import_client_dynamodb = require("@aws-sdk/client-dynamodb");
 var import_lib_dynamodb = require("@aws-sdk/lib-dynamodb");
-var KeyvDynamo = class extends import_events.default {
+var KeyvDynamo = class extends import_node_events.default {
   ttlSupport = true;
   sixHoursInMilliseconds = 6 * 60 * 60 * 1e3;
   namespace;
   opts;
   client;
+  tableReady;
   constructor(options) {
     super();
     options ??= {};
@@ -55,15 +56,17 @@ var KeyvDynamo = class extends import_events.default {
       ...options
     };
     this.client = import_lib_dynamodb.DynamoDBDocument.from(new import_client_dynamodb.DynamoDB(this.opts));
-    this.checkTableExists(this.opts.tableName).catch((error) => {
-      this.emit("error", error);
-    });
-  }
-  async checkTableExists(tableName) {
-    await this.client.send(new import_client_dynamodb.DescribeTableCommand({ TableName: tableName }));
+    this.tableReady = this.ensureTable(this.opts.tableName).catch(
+      (error) => {
+        this.emit("error", error);
+      }
+    );
   }
   async set(key, value, ttl) {
-    const sixHoursFromNowEpoch = Math.floor((Date.now() + this.sixHoursInMilliseconds) / 1e3);
+    await this.tableReady;
+    const sixHoursFromNowEpoch = Math.floor(
+      (Date.now() + this.sixHoursInMilliseconds) / 1e3
+    );
     const expiresAt = typeof ttl === "number" ? Math.floor((Date.now() + (ttl + 1e3)) / 1e3) : sixHoursFromNowEpoch;
     const putInput = {
       TableName: this.opts.tableName,
@@ -76,6 +79,7 @@ var KeyvDynamo = class extends import_events.default {
     await this.client.put(putInput);
   }
   async get(key) {
+    await this.tableReady;
     const getInput = {
       TableName: this.opts.tableName,
       Key: {
@@ -86,6 +90,7 @@ var KeyvDynamo = class extends import_events.default {
     return Item?.value;
   }
   async delete(key) {
+    await this.tableReady;
     const deleteInput = {
       TableName: this.opts.tableName,
       Key: {
@@ -97,6 +102,7 @@ var KeyvDynamo = class extends import_events.default {
     return Boolean(Attributes);
   }
   async getMany(keys) {
+    await this.tableReady;
     const batchGetInput = {
       RequestItems: {
         [this.opts.tableName]: {
@@ -107,9 +113,12 @@ var KeyvDynamo = class extends import_events.default {
       }
     };
     const { Responses: { [this.opts.tableName]: items = [] } = {} } = await this.client.batchGet(batchGetInput);
-    return keys.map((key) => items.find((item) => item?.id === key)?.value);
+    return keys.map(
+      (key) => items.find((item) => item?.id === key)?.value
+    );
   }
   async deleteMany(keys) {
+    await this.tableReady;
     if (keys.length === 0) {
       return false;
     }
@@ -133,6 +142,7 @@ var KeyvDynamo = class extends import_events.default {
     return Boolean(response);
   }
   async clear() {
+    await this.tableReady;
     const scanResult = await this.client.scan({
       TableName: this.opts.tableName
     });
@@ -142,6 +152,53 @@ var KeyvDynamo = class extends import_events.default {
   extractKey(output, keyProperty = "id") {
     return (output.Items ?? []).map((item) => item[keyProperty]).filter((key) => key.startsWith(this.namespace ?? ""));
   }
+  async ensureTable(tableName) {
+    try {
+      await this.client.send(
+        new import_client_dynamodb.DescribeTableCommand({ TableName: tableName })
+      );
+    } catch (error) {
+      if (error instanceof import_client_dynamodb.ResourceNotFoundException) {
+        await this.createTable(tableName);
+      } else {
+        throw error;
+      }
+    }
+  }
+  async createTable(tableName) {
+    try {
+      await this.client.send(
+        new import_client_dynamodb.CreateTableCommand({
+          TableName: tableName,
+          KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
+          AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
+          BillingMode: "PAY_PER_REQUEST"
+        })
+      );
+      await (0, import_client_dynamodb.waitUntilTableExists)(
+        { client: this.client, maxWaitTime: 60 },
+        { TableName: tableName }
+      );
+      await this.client.send(
+        new import_client_dynamodb.UpdateTimeToLiveCommand({
+          TableName: tableName,
+          TimeToLiveSpecification: {
+            AttributeName: "expiresAt",
+            Enabled: true
+          }
+        })
+      );
+    } catch (error) {
+      if (error instanceof import_client_dynamodb.ResourceInUseException) {
+        await (0, import_client_dynamodb.waitUntilTableExists)(
+          { client: this.client, maxWaitTime: 60 },
+          { TableName: tableName }
+        );
+      } else {
+        throw error;
+      }
+    }
+  }
 };
 var index_default = KeyvDynamo;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -1,17 +1,18 @@
-import EventEmitter from 'events';
+import EventEmitter from 'node:events';
 import { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import { KeyvStoreAdapter, StoredData } from 'keyv';
 
 declare class KeyvDynamo extends EventEmitter implements KeyvStoreAdapter {
     ttlSupport: boolean;
     sixHoursInMilliseconds: number;
     namespace?: string;
-    opts: Omit<KeyvDynamoOptions, 'tableName'> & {
+    opts: Omit<KeyvDynamoOptions, "tableName"> & {
         tableName: string;
     };
-    private readonly client;
+    readonly client: DynamoDBDocument;
+    private readonly tableReady;
     constructor(options: KeyvDynamoOptions | string);
-    checkTableExists(tableName: string): Promise<void>;
     set(key: string, value: unknown, ttl?: number): Promise<void>;
     get<Value>(key: string): Promise<StoredData<Value>>;
     delete(key: string): Promise<boolean>;
@@ -19,6 +20,8 @@ declare class KeyvDynamo extends EventEmitter implements KeyvStoreAdapter {
     deleteMany(keys: string[]): Promise<boolean>;
     clear(): Promise<void>;
     private extractKey;
+    private ensureTable;
+    private createTable;
 }
 
 type KeyvDynamoOptions = {

package/dist/index.d.ts

@@ -1,17 +1,18 @@
-import EventEmitter from 'events';
+import EventEmitter from 'node:events';
 import { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import { KeyvStoreAdapter, StoredData } from 'keyv';
 
 declare class KeyvDynamo extends EventEmitter implements KeyvStoreAdapter {
     ttlSupport: boolean;
     sixHoursInMilliseconds: number;
     namespace?: string;
-    opts: Omit<KeyvDynamoOptions, 'tableName'> & {
+    opts: Omit<KeyvDynamoOptions, "tableName"> & {
         tableName: string;
     };
-    private readonly client;
+    readonly client: DynamoDBDocument;
+    private readonly tableReady;
     constructor(options: KeyvDynamoOptions | string);
-    checkTableExists(tableName: string): Promise<void>;
     set(key: string, value: unknown, ttl?: number): Promise<void>;
     get<Value>(key: string): Promise<StoredData<Value>>;
     delete(key: string): Promise<boolean>;
@@ -19,6 +20,8 @@ declare class KeyvDynamo extends EventEmitter implements KeyvStoreAdapter {
     deleteMany(keys: string[]): Promise<boolean>;
     clear(): Promise<void>;
     private extractKey;
+    private ensureTable;
+    private createTable;
 }
 
 type KeyvDynamoOptions = {

package/dist/index.js

@@ -1,8 +1,13 @@
 // src/index.ts
 import EventEmitter from "events";
 import {
+  CreateTableCommand,
   DescribeTableCommand,
-  DynamoDB
+  DynamoDB,
+  ResourceInUseException,
+  ResourceNotFoundException,
+  UpdateTimeToLiveCommand,
+  waitUntilTableExists
 } from "@aws-sdk/client-dynamodb";
 import {
   DynamoDBDocument
@@ -13,6 +18,7 @@ var KeyvDynamo = class extends EventEmitter {
   namespace;
   opts;
   client;
+  tableReady;
   constructor(options) {
     super();
     options ??= {};
@@ -25,15 +31,17 @@ var KeyvDynamo = class extends EventEmitter {
       ...options
     };
     this.client = DynamoDBDocument.from(new DynamoDB(this.opts));
-    this.checkTableExists(this.opts.tableName).catch((error) => {
-      this.emit("error", error);
-    });
-  }
-  async checkTableExists(tableName) {
-    await this.client.send(new DescribeTableCommand({ TableName: tableName }));
+    this.tableReady = this.ensureTable(this.opts.tableName).catch(
+      (error) => {
+        this.emit("error", error);
+      }
+    );
   }
   async set(key, value, ttl) {
-    const sixHoursFromNowEpoch = Math.floor((Date.now() + this.sixHoursInMilliseconds) / 1e3);
+    await this.tableReady;
+    const sixHoursFromNowEpoch = Math.floor(
+      (Date.now() + this.sixHoursInMilliseconds) / 1e3
+    );
     const expiresAt = typeof ttl === "number" ? Math.floor((Date.now() + (ttl + 1e3)) / 1e3) : sixHoursFromNowEpoch;
     const putInput = {
       TableName: this.opts.tableName,
@@ -46,6 +54,7 @@ var KeyvDynamo = class extends EventEmitter {
     await this.client.put(putInput);
   }
   async get(key) {
+    await this.tableReady;
     const getInput = {
       TableName: this.opts.tableName,
       Key: {
@@ -56,6 +65,7 @@ var KeyvDynamo = class extends EventEmitter {
     return Item?.value;
   }
   async delete(key) {
+    await this.tableReady;
     const deleteInput = {
       TableName: this.opts.tableName,
       Key: {
@@ -67,6 +77,7 @@ var KeyvDynamo = class extends EventEmitter {
     return Boolean(Attributes);
   }
   async getMany(keys) {
+    await this.tableReady;
     const batchGetInput = {
       RequestItems: {
         [this.opts.tableName]: {
@@ -77,9 +88,12 @@ var KeyvDynamo = class extends EventEmitter {
       }
     };
     const { Responses: { [this.opts.tableName]: items = [] } = {} } = await this.client.batchGet(batchGetInput);
-    return keys.map((key) => items.find((item) => item?.id === key)?.value);
+    return keys.map(
+      (key) => items.find((item) => item?.id === key)?.value
+    );
   }
   async deleteMany(keys) {
+    await this.tableReady;
     if (keys.length === 0) {
       return false;
     }
@@ -103,6 +117,7 @@ var KeyvDynamo = class extends EventEmitter {
     return Boolean(response);
   }
   async clear() {
+    await this.tableReady;
     const scanResult = await this.client.scan({
       TableName: this.opts.tableName
     });
@@ -112,6 +127,53 @@ var KeyvDynamo = class extends EventEmitter {
   extractKey(output, keyProperty = "id") {
     return (output.Items ?? []).map((item) => item[keyProperty]).filter((key) => key.startsWith(this.namespace ?? ""));
   }
+  async ensureTable(tableName) {
+    try {
+      await this.client.send(
+        new DescribeTableCommand({ TableName: tableName })
+      );
+    } catch (error) {
+      if (error instanceof ResourceNotFoundException) {
+        await this.createTable(tableName);
+      } else {
+        throw error;
+      }
+    }
+  }
+  async createTable(tableName) {
+    try {
+      await this.client.send(
+        new CreateTableCommand({
+          TableName: tableName,
+          KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
+          AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
+          BillingMode: "PAY_PER_REQUEST"
+        })
+      );
+      await waitUntilTableExists(
+        { client: this.client, maxWaitTime: 60 },
+        { TableName: tableName }
+      );
+      await this.client.send(
+        new UpdateTimeToLiveCommand({
+          TableName: tableName,
+          TimeToLiveSpecification: {
+            AttributeName: "expiresAt",
+            Enabled: true
+          }
+        })
+      );
+    } catch (error) {
+      if (error instanceof ResourceInUseException) {
+        await waitUntilTableExists(
+          { client: this.client, maxWaitTime: 60 },
+          { TableName: tableName }
+        );
+      } else {
+        throw error;
+      }
+    }
+  }
 };
 var index_default = KeyvDynamo;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyv/dynamo",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "DynamoDB storage adapter for Keyv",
   "type": "module",
   "main": "dist/index.cjs",
@@ -12,29 +12,6 @@
       "import": "./dist/index.js"
     }
   },
-  "xo": {
-    "space": true,
-    "rules": {
-      "import/no-named-as-default": "off",
-      "unicorn/prefer-module": "off",
-      "unicorn/prefer-event-target": "off",
-      "unicorn/no-array-reduce": "off",
-      "unicorn/prefer-object-from-entries": "off",
-      "unicorn/prefer-node-protocol": "off",
-      "@typescript-eslint/no-unsafe-assignment": "off",
-      "@typescript-eslint/no-unsafe-call": "off",
-      "@typescript-eslint/no-unsafe-return": "off",
-      "@typescript-eslint/no-unsafe-argument": "off",
-      "import/extensions": "off",
-      "@typescript-eslint/consistent-type-imports": "off",
-      "@typescript-eslint/naming-convention": "off",
-      "@typescript-eslint/no-floating-promises": "off",
-      "import/no-extraneous-dependencies": "off",
-      "@typescript-eslint/no-confusing-void-expression": "off",
-      "@typescript-eslint/no-empty-function": "off",
-      "promise/prefer-await-to-then": "off"
-    }
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jaredwray/keyv.git"
@@ -58,13 +35,14 @@
   },
   "homepage": "https://github.com/jaredwray/keyv",
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.835.0",
-    "@aws-sdk/lib-dynamodb": "^3.835.0"
+    "@aws-sdk/client-dynamodb": "^3.883.0",
+    "@aws-sdk/lib-dynamodb": "^3.883.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.2.3",
     "vitest": "^3.2.4",
-    "keyv": "^5.3.4",
-    "@keyv/test-suite": "^2.0.9"
+    "@keyv/test-suite": "^2.1.1",
+    "keyv": "^5.5.1"
   },
   "tsd": {
     "directory": "test"
@@ -75,8 +53,8 @@
   ],
   "scripts": {
     "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
-    "test": "xo --fix && vitest run --coverage",
-    "test:ci": "xo && vitest --run --sequence.setupFiles=list --coverage",
+    "test": "biome check --write && vitest run --coverage",
+    "test:ci": "biome check && vitest --run --sequence.setupFiles=list --coverage",
     "clean": "rimraf ./node_modules ./coverage ./dist"
   }
 }