@moicky/dynamodb 1.1.3 → 1.2.0

package/dist/index.d.ts

@@ -1,3 +1,2 @@
-export * from "./operations";
 export * from "./lib/client";
-export * from "./lib/helpers";
+export * from "./operations";

package/dist/index.js

@@ -14,6 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./operations"), exports);
 __exportStar(require("./lib/client"), exports);
-__exportStar(require("./lib/helpers"), exports);
+__exportStar(require("./operations"), exports);

package/dist/lib/client.d.ts

@@ -1,3 +1,30 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+declare interface KeySchema {
+    hash: string;
+    range?: string;
+}
+declare interface KeySchemaCollection {
+    [tableName: string]: KeySchema;
+}
+declare class DynamoDBConfig {
+    #private;
+    client: DynamoDBClient;
+    tablesSchema: KeySchemaCollection;
+    constructor({ region }?: {
+        region?: string;
+    });
+    initSchema(schema: KeySchemaCollection): KeySchemaCollection;
+    getDefaultTable(): string;
+    getTableSchema(tableName?: string): KeySchema;
+    getDefaultTableSchema(): KeySchema;
+    validateSchema(schema: KeySchemaCollection): boolean;
+    destroy(): void;
+}
+declare const config: DynamoDBConfig;
 export declare const client: DynamoDBClient;
-export declare const TableName: string;
+export declare const getDefaultTable: () => string;
+export declare const getTableSchema: (tableName?: string) => KeySchema;
+export declare const getDefaultTableSchema: () => KeySchema;
+export declare const initSchema: (schema: KeySchemaCollection) => KeySchemaCollection;
+export declare const destroy: () => void;
+export default config;

package/dist/lib/client.js

@@ -1,11 +1,78 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TableName = exports.client = void 0;
+exports.destroy = exports.initSchema = exports.getDefaultTableSchema = exports.getTableSchema = exports.getDefaultTable = exports.client = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
-exports.client = new client_dynamodb_1.DynamoDBClient({
-    region: process.env.AWS_REGION || "eu-central-1",
-});
-exports.TableName = process.env.DYNAMODB_TABLE;
-if (!exports.TableName) {
-    throw new Error("Missing DYNAMODB_TABLE environment variable");
+class DynamoDBConfig {
+    client;
+    tablesSchema = {};
+    #initialized = false;
+    constructor({ region } = {}) {
+        this.client = new client_dynamodb_1.DynamoDBClient({
+            region: region || process.env.AWS_REGION || "eu-central-1",
+        });
+        const defaultTable = process.env.DYNAMODB_TABLE;
+        if (defaultTable) {
+            this.tablesSchema[defaultTable] = {
+                hash: "PK",
+                range: "SK",
+            };
+            this.#initialized = true;
+        }
+    }
+    initSchema(schema) {
+        if (!this.validateSchema(schema)) {
+            throw new Error("Invalid schema");
+        }
+        this.tablesSchema = Object.keys(schema).reduce((acc, table) => {
+            const { hash, range } = schema[table];
+            acc[table] = {
+                hash: hash + "",
+                ...(range && { range: range + "" }),
+            };
+            return acc;
+        }, {});
+        this.#initialized = true;
+        return this.tablesSchema;
+    }
+    getDefaultTable() {
+        if (!this.#initialized) {
+            throw new Error("Schema not initialized");
+        }
+        const table = Object.keys(this.tablesSchema)[0];
+        return table;
+    }
+    getTableSchema(tableName) {
+        if (!this.#initialized) {
+            throw new Error("Schema not initialized");
+        }
+        const table = tableName || this.getDefaultTable();
+        return this.tablesSchema[table] || this.getDefaultTableSchema();
+    }
+    getDefaultTableSchema() {
+        return { hash: "PK", range: "SK" };
+    }
+    validateSchema(schema) {
+        const tables = Object.keys(schema);
+        if (tables.length === 0) {
+            throw new Error("No tables provided");
+        }
+        tables.forEach((table) => {
+            const { hash } = schema[table];
+            if (!hash) {
+                throw new Error(`No hash key provided for table ${table}`);
+            }
+        });
+        return true;
+    }
+    destroy() {
+        this.client.destroy();
+    }
 }
+const config = new DynamoDBConfig();
+exports.client = config.client;
+exports.getDefaultTable = config.getDefaultTable.bind(config);
+exports.getTableSchema = config.getTableSchema.bind(config);
+exports.getDefaultTableSchema = config.getDefaultTableSchema.bind(config);
+exports.initSchema = config.initSchema.bind(config);
+exports.destroy = config.destroy.bind(config);
+exports.default = config;

package/dist/lib/helpers.d.ts

@@ -1,4 +1,6 @@
-export declare function stripKey(key: any): Record<string, any>;
+export declare function stripKey(key: any, args?: {
+    TableName?: string;
+}): Record<string, any>;
 export declare function splitEvery<T>(items: T[], limit?: number): T[][];
 export declare function getAttributeValues(key: any, attributesToGet?: string[]): Record<string, any>;
 export declare function getAttributeNames(key: any, attributesToGet?: string[]): Record<string, string>;

package/dist/lib/helpers.js

@@ -2,12 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAttributesFromExpression = exports.getAttributeNames = exports.getAttributeValues = exports.splitEvery = exports.stripKey = void 0;
 const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
-// ----- Configuration -----
+const client_1 = require("../lib/client");
 // Since dynamo only accepts key atrtributes which are described in table schema
 // we remove any other attributes from the item if they are present and passed as
 // key parameter to any of the functions below (getItem, updateItem, deleteItem...)
-function stripKey(key) {
-    return (0, util_dynamodb_1.marshall)({ PK: key.PK, SK: key.SK });
+function stripKey(key, args) {
+    const { hash, range } = (0, client_1.getTableSchema)(args?.TableName);
+    return (0, util_dynamodb_1.marshall)({
+        [hash]: key[hash],
+        ...(range && { [range]: key[range] }),
+    });
 }
 exports.stripKey = stripKey;
 function splitEvery(items, limit = 25) {

package/dist/operations/delete.d.ts

@@ -1,3 +1,5 @@
 import { BatchWriteItemCommandInput, DeleteItemCommandInput, DeleteItemCommandOutput } from "@aws-sdk/client-dynamodb";
 export declare function deleteItem(key: any, args?: Partial<DeleteItemCommandInput>): Promise<DeleteItemCommandOutput>;
-export declare function deleteItems(keys: any[], args?: Partial<BatchWriteItemCommandInput>, retry?: number): Promise<void>;
+export declare function deleteItems(keys: any[], args?: Partial<BatchWriteItemCommandInput & {
+    TableName?: string;
+}>, retry?: number): Promise<void>;

package/dist/operations/delete.js

@@ -6,15 +6,15 @@ const client_1 = require("../lib/client");
 const helpers_1 = require("../lib/helpers");
 async function deleteItem(key, args = {}) {
     return client_1.client.send(new client_dynamodb_1.DeleteItemCommand({
-        TableName: client_1.TableName,
-        Key: (0, helpers_1.stripKey)(key),
+        Key: (0, helpers_1.stripKey)(key, args),
         ...args,
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
     }));
 }
 exports.deleteItem = deleteItem;
 async function deleteItems(keys, args = {}, retry = 0) {
     const uniqueKeys = Object.values(keys.reduce((acc, key) => {
-        const strippedKey = (0, helpers_1.stripKey)(key);
+        const strippedKey = (0, helpers_1.stripKey)(key, args);
         const keyString = JSON.stringify(strippedKey);
         if (!acc[keyString]) {
             acc[keyString] = strippedKey;
@@ -25,11 +25,12 @@ async function deleteItems(keys, args = {}, retry = 0) {
         const batches = (0, helpers_1.splitEvery)(uniqueKeys);
         if (retry > 3)
             return;
+        const table = args?.TableName || (0, client_1.getDefaultTable)();
         for (const batch of batches) {
             await client_1.client
                 .send(new client_dynamodb_1.BatchWriteItemCommand({
                 RequestItems: {
-                    [client_1.TableName]: batch.map((Key) => ({
+                    [table]: batch.map((Key) => ({
                         DeleteRequest: {
                             Key,
                         },
@@ -38,10 +39,10 @@ async function deleteItems(keys, args = {}, retry = 0) {
                 ...args,
             }))
                 .then((res) => {
-                if (res?.UnprocessedItems?.[client_1.TableName]?.length) {
+                if (res?.UnprocessedItems?.[table]?.length) {
                     if (retry + 1 > 3)
                         return reject(res);
-                    return deleteItems(res.UnprocessedItems[client_1.TableName], args, retry + 1);
+                    return deleteItems(res.UnprocessedItems[table], args, retry + 1);
                 }
             })
                 .catch(reject);

package/dist/operations/get.d.ts

@@ -1,4 +1,6 @@
 import { BatchGetItemCommandInput, GetItemCommandInput, ScanCommandInput } from "@aws-sdk/client-dynamodb";
-export declare function getItem(key: any, args?: Partial<GetItemCommandInput>): Promise<Record<string, any>>;
-export declare function getItems(keys: any[], args?: Partial<BatchGetItemCommandInput>, retry?: number): Promise<Record<string, any>[]>;
+export declare function getItem(key: any, args?: Partial<GetItemCommandInput>): Promise<Record<string, any> | undefined>;
+export declare function getItems(keys: any[], args?: Partial<BatchGetItemCommandInput & {
+    TableName?: string;
+}>, retry?: number): Promise<Record<string, any>[]>;
 export declare function getAllItems(args?: Partial<ScanCommandInput>): Promise<Record<string, any>[]>;

package/dist/operations/get.js

@@ -8,9 +8,9 @@ const helpers_1 = require("../lib/helpers");
 async function getItem(key, args = {}) {
     return client_1.client
         .send(new client_dynamodb_1.GetItemCommand({
-        TableName: client_1.TableName,
-        Key: (0, helpers_1.stripKey)(key),
+        Key: (0, helpers_1.stripKey)(key, args),
         ...args,
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
     }))
         .then((res) => res?.Item && (0, util_dynamodb_1.unmarshall)(res.Item));
 }
@@ -24,7 +24,7 @@ async function getItems(keys, args = {}, retry = 0) {
     const batchReadLimit = 100;
     // duplicate key entries would cause an error, so we remove them
     const uniqueKeys = Object.values(keys.reduce((acc, key) => {
-        const strippedKey = (0, helpers_1.stripKey)(key);
+        const strippedKey = (0, helpers_1.stripKey)(key, args);
         const keyString = JSON.stringify(strippedKey);
         if (!acc[keyString]) {
             acc[keyString] = strippedKey;
@@ -36,21 +36,23 @@ async function getItems(keys, args = {}, retry = 0) {
     if (retry > 2) {
         return results;
     }
+    const TableName = args?.TableName || (0, client_1.getDefaultTable)();
+    delete args.TableName;
     await Promise.all(batches.map(async (batch) => {
         await client_1.client
             .send(new client_dynamodb_1.BatchGetItemCommand({
             RequestItems: {
-                [client_1.TableName]: {
+                [TableName]: {
                     Keys: batch,
                     ...args,
                 },
             },
         }))
             .then((res) => {
-            const unprocessed = res?.UnprocessedKeys?.[client_1.TableName];
-            const allItemsFromBatch = res?.Responses?.[client_1.TableName] || [];
+            const unprocessed = res?.UnprocessedKeys?.[TableName];
+            const allItemsFromBatch = res?.Responses?.[TableName] || [];
             if (unprocessed) {
-                return getItems(unprocessed.Keys, args, retry + 1).then((items) => allItemsFromBatch.concat(items));
+                return getItems(unprocessed.Keys, { ...args, TableName }, retry + 1).then((items) => allItemsFromBatch.concat(items));
             }
             return allItemsFromBatch.map((item) => item && (0, util_dynamodb_1.unmarshall)(item));
         })
@@ -59,18 +61,18 @@ async function getItems(keys, args = {}, retry = 0) {
     const resultItems = results
         .filter((i) => i)
         .reduce((acc, item) => {
-        const keyString = JSON.stringify((0, helpers_1.stripKey)(item));
+        const keyString = JSON.stringify((0, helpers_1.stripKey)(item, { TableName }));
         acc[keyString] = item;
         return acc;
     }, {});
-    return keys.map((key) => resultItems[JSON.stringify((0, helpers_1.stripKey)(key))] || undefined);
+    return keys.map((key) => resultItems[JSON.stringify((0, helpers_1.stripKey)(key, { TableName }))] || undefined);
 }
 exports.getItems = getItems;
 async function getAllItems(args = {}) {
     return client_1.client
         .send(new client_dynamodb_1.ScanCommand({
-        TableName: client_1.TableName,
         ...args,
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
     }))
         .then((res) => res.Items.map((item) => item && (0, util_dynamodb_1.unmarshall)(item)));
 }

package/dist/operations/misc.d.ts

@@ -1,7 +1,7 @@
 import { GetItemCommandInput } from "@aws-sdk/client-dynamodb";
 export declare function itemExists(key: any, args?: Partial<GetItemCommandInput>): Promise<boolean>;
-export declare function getNewId({ PK, SK, length, }: {
-    PK: string;
-    SK?: string;
+export declare function getAscendingId({ length, TableName, ...keySchema }: {
     length?: number;
+    TableName?: string;
+    [keySchema: string]: any;
 }): Promise<string>;

package/dist/operations/misc.js

@@ -1,32 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getNewId = exports.itemExists = void 0;
+exports.getAscendingId = exports.itemExists = void 0;
+const client_1 = require("../lib/client");
 const get_1 = require("./get");
 const query_1 = require("./query");
 async function itemExists(key, args = {}) {
-    const item = await (0, get_1.getItem)(key, args);
-    return item !== undefined && item !== null;
+    return !!(await (0, get_1.getItem)(key, args));
 }
 exports.itemExists = itemExists;
-async function getNewId({ PK, SK, length = 8, }) {
-    // Assumes that you are using SK as the incrementing ID
-    if (!PK) {
-        throw new Error("Cannot generate new ID: PK");
+async function getAscendingId({ length = 8, TableName, ...keySchema }) {
+    // Assumes that you are the incrementing ID inside or as the keySchema range key
+    const table = TableName || (0, client_1.getDefaultTable)();
+    const { hash, range } = (0, client_1.getTableSchema)(table);
+    const keySchemaHash = keySchema[hash];
+    const keySchemaRange = keySchema[range];
+    if (!keySchemaHash) {
+        throw new Error(`Cannot generate new ID: keySchemaHash is missing, expected '${hash}'`);
     }
     let lastId = "0";
-    if (!SK) {
-        const lastItem = (await (0, query_1.queryItems)("#PK = :PK", { PK }, { Limit: 1, ScanIndexForward: false }))?.[0];
-        const parts = lastItem?.["SK"]?.split("/") || [];
+    if (!keySchemaRange) {
+        const lastItem = (await (0, query_1.queryItems)(`#${hash} = :${hash}`, { [hash]: keySchemaHash }, { Limit: 1, ScanIndexForward: false, TableName: table }))?.[0];
+        const parts = lastItem?.[range]?.split("/") || [];
         lastId = parts?.[parts.length - 1] || "0";
     }
     else {
-        const formattedSK = SK + (!SK.endsWith("/") ? "/" : "");
-        const lastItem = (await (0, query_1.queryItems)("#PK = :PK and begins_with(#SK, :SK)", { PK, SK: formattedSK }, { Limit: 1, ScanIndexForward: false }))?.[0];
-        const parts = lastItem?.["SK"]?.split("/") || [];
+        const formattedSK = keySchemaRange + (!keySchemaRange.endsWith("/") ? "/" : "");
+        const lastItem = (await (0, query_1.queryItems)(`#${hash} = :${hash} and begins_with(#${range}, :${range})`, { [hash]: keySchemaHash, [range]: formattedSK }, { Limit: 1, ScanIndexForward: false, TableName: table }))?.[0];
+        const parts = lastItem?.[range]?.split("/") || [];
         lastId = parts?.[formattedSK.split("/").length - 1] || "0";
     }
     const newId = parseInt(lastId) + 1 + "";
     const withPadding = newId.padStart(length || 0, "0");
     return withPadding;
 }
-exports.getNewId = getNewId;
+exports.getAscendingId = getAscendingId;

package/dist/operations/put.d.ts

@@ -1,3 +1,5 @@
-import { BatchWriteItemCommandInput, PutItemCommandInput, PutItemCommandOutput } from "@aws-sdk/client-dynamodb";
-export declare function putItem(data: any, args?: Partial<PutItemCommandInput>): Promise<PutItemCommandOutput>;
-export declare function putItems(items: any[], args?: Partial<BatchWriteItemCommandInput>): Promise<void>;
+import { BatchWriteItemCommandInput, BatchWriteItemCommandOutput, PutItemCommandInput, PutItemCommandOutput } from "@aws-sdk/client-dynamodb";
+export declare function putItem(data: any, args?: Partial<PutItemCommandInput>): Promise<PutItemCommandOutput | Record<string, any>>;
+export declare function putItems(items: any[], args?: Partial<BatchWriteItemCommandInput & {
+    TableName?: string;
+}>): Promise<BatchWriteItemCommandOutput[]>;

package/dist/operations/put.js

@@ -9,27 +9,29 @@ async function putItem(data, args = {}) {
     if (!Object.keys(data).includes("createdAt")) {
         data.createdAt = Date.now();
     }
-    return client_1.client.send(new client_dynamodb_1.PutItemCommand({
-        TableName: client_1.TableName,
+    return client_1.client
+        .send(new client_dynamodb_1.PutItemCommand({
         Item: (0, util_dynamodb_1.marshall)(data),
         ...args,
-    }));
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
+    }))
+        .then((res) => (args?.ReturnValues ? (0, util_dynamodb_1.unmarshall)(res?.Attributes) : res));
 }
 exports.putItem = putItem;
 async function putItems(items, args = {}) {
     return new Promise(async (resolve, reject) => {
-        const batches = (0, helpers_1.splitEvery)(items);
         const now = Date.now();
+        const batches = (0, helpers_1.splitEvery)(items.map((item) => ({
+            ...item,
+            createdAt: item?.createdAt ?? now,
+        })));
+        const results = [];
+        const table = args?.TableName || (0, client_1.getDefaultTable)();
         for (const batch of batches) {
-            batch.forEach((item) => {
-                if (!Object.keys(item).includes("createdAt")) {
-                    item.createdAt = now;
-                }
-            });
             await client_1.client
                 .send(new client_dynamodb_1.BatchWriteItemCommand({
                 RequestItems: {
-                    [client_1.TableName]: batch.map((item) => ({
+                    [table]: batch.map((item) => ({
                         PutRequest: {
                             Item: (0, util_dynamodb_1.marshall)(item),
                         },
@@ -37,9 +39,10 @@ async function putItems(items, args = {}) {
                 },
                 ...args,
             }))
+                .then((res) => results.push(res))
                 .catch(reject);
         }
-        resolve();
+        resolve(results);
     });
 }
 exports.putItems = putItems;

package/dist/operations/query.js

@@ -7,7 +7,6 @@ const client_1 = require("../lib/client");
 const helpers_1 = require("../lib/helpers");
 async function query(keyCondition, key, args = {}) {
     return client_1.client.send(new client_dynamodb_1.QueryCommand({
-        TableName: client_1.TableName,
         KeyConditionExpression: keyCondition,
         ExpressionAttributeValues: (0, helpers_1.getAttributeValues)(key, [
             ...(0, helpers_1.getAttributesFromExpression)(keyCondition, ":"),
@@ -18,6 +17,7 @@ async function query(keyCondition, key, args = {}) {
             ...(0, helpers_1.getAttributesFromExpression)(args?.FilterExpression || ""),
         ]),
         ...args,
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
     }));
 }
 exports.query = query;

package/dist/operations/update.d.ts

@@ -1,3 +1,3 @@
 import { UpdateItemCommandInput, UpdateItemCommandOutput } from "@aws-sdk/client-dynamodb";
 export declare function updateItem(key: any, data: any, args?: Partial<UpdateItemCommandInput>): Promise<undefined | Record<string, any>>;
-export declare function removeAttributes(key: any, attributes: string[]): Promise<UpdateItemCommandOutput>;
+export declare function removeAttributes(key: any, attributes: string[], args?: Partial<UpdateItemCommandInput>): Promise<UpdateItemCommandOutput>;

package/dist/operations/update.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeAttributes = exports.updateItem = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
 const client_1 = require("../lib/client");
 const helpers_1 = require("../lib/helpers");
-const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
 async function updateItem(key, data, args = {}) {
     if (!Object.keys(data).includes("updatedAt")) {
         data.updatedAt = Date.now();
@@ -15,8 +15,7 @@ async function updateItem(key, data, args = {}) {
     const UpdateExpression = "SET " + attributesToUpdate.map((key) => `#${key} = :${key}`).join(", ");
     return client_1.client
         .send(new client_dynamodb_1.UpdateItemCommand({
-        TableName: client_1.TableName,
-        Key: (0, helpers_1.stripKey)(key),
+        Key: (0, helpers_1.stripKey)(key, args),
         UpdateExpression,
         ExpressionAttributeValues: (0, helpers_1.getAttributeValues)(data, [
             ...attributesToUpdate,
@@ -27,20 +26,22 @@ async function updateItem(key, data, args = {}) {
             ...namesInCondition,
         ]),
         ...args,
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
     }))
         .then((res) => args?.ReturnValues ? (0, util_dynamodb_1.unmarshall)(res.Attributes) : undefined);
 }
 exports.updateItem = updateItem;
-async function removeAttributes(key, attributes) {
+async function removeAttributes(key, attributes, args = {}) {
     const UpdateExpression = "REMOVE " + attributes.map((att) => `#${att}`).join(", ");
     return client_1.client.send(new client_dynamodb_1.UpdateItemCommand({
-        TableName: client_1.TableName,
-        Key: (0, helpers_1.stripKey)(key),
+        Key: (0, helpers_1.stripKey)(key, args),
         UpdateExpression,
         ExpressionAttributeNames: (0, helpers_1.getAttributeNames)(attributes.reduce((acc, att) => {
             acc[att] = att;
             return acc;
         }, {})),
+        ...args,
+        TableName: args?.TableName || (0, client_1.getDefaultTable)(),
     }));
 }
 exports.removeAttributes = removeAttributes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moicky/dynamodb",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "description": "Contains a collection of convenience functions for working with AWS DynamoDB",

package/readme.md

@@ -1,10 +1,9 @@
 # @moicky/dynamodb
 
-![](https://img.shields.io/github/languages/top/moicky/dynamodb)
 ![](https://img.shields.io/github/actions/workflow/status/moicky/dynamodb/npm-publish.yml?label=build)
 ![](https://img.shields.io/github/actions/workflow/status/moicky/dynamodb/run-tests.yml?label=tests)
 ![](https://img.shields.io/github/languages/count/moicky/dynamodb)
-![](https://img.shields.io/bundlephobia/min/@moicky/dynamodb)
+![](https://img.shields.io/tokei/lines/github/moicky/dynamodb)
 
 ## Description
 
@@ -25,9 +24,49 @@ npm i @moicky/dynamodb
 
 ## Setup
 
-Add `DYNAMODB_TABLE` as an **environment variable** containing the name of the dynamodb table. Also make sure to setup the required permissions to access the dynamodb table on aws or on your local machine. Also make sure to use `PK` and `SK` as keySchema attribute names in the table.
+Requires a **keySchema** definition to be setup. Automatically grabs `DYNAMODB_TABLE` as an **environment variable** and uses `PK` and `SK` for it's schema. Can be overwritten using `initSchema` with multiple tables:
 
-_Support for different keySchemas will follow 😉_
+```ts
+import { initSchema } from "@moicky/dynamodb";
+
+// Should be called once at the start of the runtime before any operation is executed
+initSchema({
+  // first one will be used if no TableName is specified
+  [process.env.DEFAULT_TABLE]: {
+    hash: "PK",
+    range: "SK",
+  },
+  [process.env.SECOND_TABLE]: {
+    hash: "bookId",
+  },
+});
+```
+
+## Working with multiple tables
+
+Every function accepts `args` which can include a `TableName` property that specifies the table and uses the keySchema from `initSchema()`
+
+```ts
+import { getItem, putItem, deleteItem } from "@moicky/dynamodb";
+
+await putItem(
+  {
+    PK: "User/1",
+    someSortKey: "Book/1",
+    title: "The Great Gatsby",
+    author: "F. Scott Fitzgerald",
+    released: 1925,
+  },
+  { TableName: process.env.SECOND_TABLE }
+);
+
+const item = await getItem(
+  { PK: "User/1", someSortKey: "Book/1" },
+  { TableName: process.env.SECOND_TABLE }
+);
+
+await deleteItem(item, { TableName: process.env.SECOND_TABLE });
+```
 
 ## Usage Examples
 
@@ -186,30 +225,170 @@ const booksWithFilter = await queryAllItems(
 ### Miscellaneous
 
 ```ts
-import { itemExists, getNewId } from "@moicky/dynamodb";
+import { itemExists, getAscendingId } from "@moicky/dynamodb";
 
 // Check if an item exists using keySchema
 const exists = await itemExists({ PK: "User/1", SK: "Book/1" });
 
 // Generate ascending ID
+// Specify keySchemaHash and optionally item to start at using keySchemaRange
 
 // Example Structure 1: PK: "User/1", SK: "{{ ASCENDING_ID }}"
 // Last item: { PK: "User/1", SK: "00000009" }
-const id1 = await getNewId({ PK: "User/1" });
+const id1 = await getAscendingId({ PK: "User/1" });
 console.log(id1); // "00000010"
 
 // Example Structure 2: PK: "User/1", SK: "Book/{{ ASCENDING_ID }}"
 // Last item: { PK: "User/1", SK: "Book/00000009" }
-const id2 = await getNewId({ PK: "User/1", SK: "Book" });
+const id2 = await getAscendingId({ PK: "User/1", SKPrefix: "Book" });
 console.log(id2); // "00000010"
 
 // Specify length of ID
-const id3 = await getNewId({ PK: "User/1", SK: "Book", length: 4 });
+const id3 = await getAscendingId({ PK: "User/1", SKPrefix: "Book", length: 4 });
 console.log(id3); // "0010"
+
+// Example Structure 3: someKeySchemaHash: "User/1", SK: "Book/{{ ASCENDING_ID }}"
+// Last item: { someKeySchemaHash: "User/1", SK: "Book/00000009" }
+const id4 = await getAscendingId({
+  someKeySchemaHash: "User/1",
+  SKPrefix: "Book",
+});
+console.log(id4); // "00000010"
+```
+
+## Why should I use this?
+
+Generally it makes it easier to interact with the dynamodb from AWS. Here are some before and after examples using the new aws-sdk v3:
+
+### Put
+
+```js
+const demoItem = {
+  PK: "User/1",
+  SK: "Book/1",
+  title: "The Great Gatsby",
+  author: "F. Scott Fitzgerald",
+  released: 1925,
+};
+
+// Without helpers:
+import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+
+const client = new DynamoDBClient({
+  region: process.env.AWS_REGION,
+});
+
+const newItem = await client
+  .send(
+    new PutItemCommand({
+      TableName: process.env.DYNAMODB_TABLE,
+      Item: marshall(demoItem),
+      ReturnValues: "ALL_NEW",
+    })
+  )
+  .then((result) => unmarshall(result.Attributes));
+
+// With helpers:
+import { putItem } from "@moicky/dynamodb";
+
+const newItem = await putItem(demoItem, { ReturnValues: "ALL_NEW" });
+```
+
+### Query
+
+```js
+// Without helpers:
+import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+
+const client = new DynamoDBClient({
+  region: process.env.AWS_REGION,
+});
+
+const results = await client
+  .send(
+    new QueryCommand({
+      TableName: process.env.DYNAMODB_TABLE,
+      KeyConditionExpression: "#PK = :PK and begins_with(#SK, :SK)",
+      ExpressionAttributeNames: {
+        "#PK": "PK",
+        "#SK": "SK",
+      },
+      ExpressionAttributeValues: {
+        ":PK": marshall("User/1"),
+        ":SK": marshall("Book/"),
+      },
+    })
+  )
+  .then((result) => result.Items.map((item) => unmarshall(item)));
+
+// With helpers
+import { queryItems } from "@moicky/dynamodb";
+
+const results = await queryItems("#PK = :PK and begins_with(#SK, :SK)", {
+  PK: "User/1",
+  SK: "Book/",
+});
+```
+
+### Update
+
+```js
+// Without helpers
+import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+
+const client = new DynamoDBClient({
+  region: process.env.AWS_REGION,
+});
+
+const result = await client
+  .send(
+    new UpdateItemCommand({
+      TableName: process.env.DYNAMODB_TABLE,
+      Key: marshall({ PK: "User/1", SK: "Book/1" }),
+      UpdateExpression: "SET #released = :released, #title = :title",
+      ExpressionAttributeNames: {
+        "#released": "released",
+        "#title": "title",
+      },
+      ExpressionAttributeValues: marshall({
+        ":released": 2000,
+        ":title": "New Title",
+      }),
+      ReturnValues: "ALL_NEW",
+    })
+  )
+  .then((result) => unmarshall(result.Attributes));
+
+// With helpers
+import { updateItem } from "@aws-sdk/lib-dynamodb";
+
+const result = await updateItem(
+  { PK: "User/1", SK: "Book/1" },
+  { released: 2000, title: "New Title" },
+  { ReturnValues: "ALL_NEW" }
+);
 ```
 
 ## Tests
 
+### Setup
+
+Requires `DEFAULT_TABLE` and `SECOND_TABLE` to be present inside the environment (`.env file`)
+Can be deployed using the `template.yml` on aws:
+
+```bash
+sam deploy
+```
+
+Will then return the table-names as the output of the template
+
+### Execution
+
+Finally executing all tests:
+
 ```bash
 npm run test
 ```