@kravc/dos-dynamodb 1.0.0-alpha.0

package/example/Organization.ts

@@ -0,0 +1,61 @@
+import { DocumentWithHashId, ExpressionKey, SortExpressionKey } from '../src';
+import { type QueryMap, type Context, type IndexAllOptions } from '@kravc/dos';
+import { schema, OrganizationStatus, type OrganizationAttributes } from './OrganizationAttributes';
+
+const PLATFORM_PARTITION = 'PLATFORM';
+
+/** Organization document class. */
+class Organization extends DocumentWithHashId<OrganizationAttributes> {
+  /** Returns a PLATFORM partition to save a document. */
+  static getPartition(): string {
+    return PLATFORM_PARTITION;
+  }
+
+  /** Returns active assets. */
+  static async listActiveOrganizations(
+    context: Context,
+    query: QueryMap = {},
+    options: IndexAllOptions = {}
+  ) {
+    const status = OrganizationStatus.ACTIVE;
+
+    const {
+      indexName,
+      sortKeyName,
+      partitionKeyName,
+    } = this.getGlobalIndexProps('gsi1');
+
+    const indexQuery = {
+      [partitionKeyName]: PLATFORM_PARTITION,
+      [`${sortKeyName}:${SortExpressionKey.BW}`]: `#${status}`,
+    } as Record<string, string>;
+
+    return this.indexAll(context, { ...query, ...indexQuery }, { ...options, indexName });
+  }
+
+  /** Disables an organization. */
+  static async disable(context: Context, query: QueryMap) {
+    query[`status:${ExpressionKey.NOT}`] = OrganizationStatus.DISABLED;
+
+    const mutation = {
+      status: OrganizationStatus.DISABLED,
+    };
+
+    return this.update(context, query, mutation);
+  }
+
+  /** Enables an organization. */
+  static async enable(context: Context, query: QueryMap) {
+    query[`status:${ExpressionKey.NOT}`] = OrganizationStatus.ACTIVE;
+
+    const mutation = {
+      status: OrganizationStatus.ACTIVE,
+    };
+
+    return this.update(context, query, mutation);
+  }
+};
+
+Organization.schema = schema;
+
+export default Organization;

package/example/OrganizationAttributes.ts

@@ -0,0 +1,28 @@
+import { Schema } from '@kravc/schema';
+import { DefaultAttributes } from '../src';
+
+export enum OrganizationStatus {
+  ACTIVE = 'ACTIVE',
+  DISABLED = 'DISABLED'
+}
+
+export interface OrganizationAttributes extends DefaultAttributes {
+  name: string;
+  status: OrganizationStatus;
+  number: number;
+}
+
+export const schema = new Schema({
+  name: {
+    required: true
+  },
+  status: {
+    enum: [ OrganizationStatus.ACTIVE, OrganizationStatus.DISABLED ],
+    required: true,
+  },
+  number: {
+    type: 'integer',
+    minimum: 1,
+    required: true,
+  }
+}, 'OrganizationBody');

package/example/index.ts

@@ -0,0 +1,9 @@
+import Asset from './Asset';
+import Activity from './Activity';
+import Organization from './Organization';
+
+export {
+  Asset,
+  Activity,
+  Organization,
+};

package/jest.config.mjs

@@ -0,0 +1,10 @@
+export default {
+  bail: true,
+  preset: 'ts-jest',
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
+  maxWorkers: 1,
+  collectCoverageFrom: [
+    '<rootDir>/src/**/*.ts',
+    '<rootDir>/example/**/*.ts'
+  ],
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kravc/dos-dynamodb",
+  "version": "1.0.0-alpha.0",
+  "description": "CRUD interface for DynamoDB table to be used with @kravc/dos service.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/alexkravets/dos-dynamodb.git"
+  },
+  "directories": {
+    "src": "src"
+  },
+  "scripts": {
+    "test": "eslint --fix src/ example/ && npm run db:up && sleep 2 && jest --coverage",
+    "prebuild": "rimraf dist",
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "db:up": "docker compose --project-name dos -f ./docker-compose.yaml up -d"
+  },
+  "bin": {
+    "table": "bin/table.js"
+  },
+  "author": "Oleksandr Kravets <alex@slatestudio.com>",
+  "license": "ISC",
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.995.0",
+    "@aws-sdk/credential-providers": "^3.995.0",
+    "@aws-sdk/lib-dynamodb": "^3.995.0",
+    "@kravc/dos": "^2.0.0-alpha.12",
+    "config": "^4.3.0",
+    "hashids": "^2.3.0",
+    "lodash": "^4.17.23"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/config": "^3.3.5",
+    "@types/jest": "^30.0.0",
+    "@types/lodash": "^4.17.23",
+    "eslint": "^10.0.1",
+    "eslint-plugin-jsdoc": "^62.7.0",
+    "globals": "^17.3.0",
+    "jest": "^30.2.0",
+    "rimraf": "^6.1.3",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0"
+  }
+}

package/src/Document/DefaultAttributes.d.ts

@@ -0,0 +1,16 @@
+import { DefaultAttributes as CommonAttributes } from '@kravc/dos';
+
+export interface DefaultAttributes extends CommonAttributes {
+  _lsi1SortKey?: string;
+  _lsi2SortKey?: string;
+  _lsi3SortKey?: string;
+
+  _gsi1PartitionKey?: string;
+  _gsi1SortKey?: string;
+
+  _gsi2PartitionKey?: string;
+  _gsi2SortKey?: string;
+
+  _gsi3PartitionKey?: string;
+  _gsi3SortKey?: string;
+}

package/src/Document/Document.ts

@@ -0,0 +1,257 @@
+import config from 'config';
+import { composeIndexKeys } from './helpers';
+import { get, set, unset, cloneDeep } from 'lodash';
+import Table, { type ItemAttributes, SortExpressionKey } from '../Table';
+import {
+  type Context,
+  type QueryMap,
+  type MutationMap,
+  type IndexOptions,
+  type IndexAllOptions,
+  got,
+  MemoryDocument,
+  DocumentExistsError,
+  DocumentNotFoundError,
+} from '@kravc/dos';
+
+const DEFAULT_PARTITION_PATH = 'identity.organizationId';
+
+const QUERY_ERROR_TEMPLATE = 'Query parameter "$PATH" is required';
+const ATTRIBUTE_ERROR_TEMPLATE = 'Attribute "$PATH" is required';
+
+const INDEX_ALL_LIMIT = 300;
+const INDEX_LIMIT_MAX = 999;
+
+/** Document class with DynamoDB database interface. */
+class Document<T> extends MemoryDocument<T> {
+  /** Returns the table instance used to store a document. */
+  static get table(): Table {
+    return new Table({
+      sortKey: this.idKey,
+      partitionKey: this.partitionKey,
+    });
+  }
+
+  /** Returns prefix for new document IDs. */
+  static get idPrefix(): string {
+    return config.get(`idPrefixes.${this.name}`);
+  }
+
+  /** Returns context path to get partition value from. */
+  static get partitionContextPath() {
+    return DEFAULT_PARTITION_PATH;
+  }
+
+  /** Returns the partition to save a document to. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static getPartition(context: Context, _parameters: Record<string, unknown>): string {
+    const errorTemplate = 'Context is missing "$PATH", partition is not defined';
+    const partition = got(context, this.partitionContextPath, errorTemplate) as string;
+
+    return partition;
+  }
+
+  /** Defines limit maximum value for index action. */
+  static get indexLimitMax(): number {
+    return INDEX_LIMIT_MAX;
+  }
+
+  /** Returns sort key name for a local secondary index. */
+  static getLocalIndexSortKeyName(indexName: string): string {
+    return this.table.options.getLocalIndexSortKeyName(indexName);
+  }
+
+  /** Returns partition key name for a global secondary index. */
+  static getGlobalIndexPartitionKeyName(indexName: string): string {
+    return this.table.options.getGlobalIndexPartitionKeyName(indexName);
+  }
+
+  /** Returns sort key name for a global secondary index. */
+  static getGlobalIndexSortKeyName(indexName: string): string {
+    return this.table.options.getGlobalIndexSortKeyName(indexName);
+  }
+
+  /** Returns true if local index, false if global index. */
+  static isLocalSecondaryIndex(indexName: string): boolean {
+    return this.table.options.isLocalSecondaryIndex(indexName);
+  }
+
+  /** Returns local index props. */
+  static getLocalIndexProps(indexName: string) {
+    return this.table.options.getLocalIndexProps(indexName);
+  }
+
+  /** Returns global index props. */
+  static getGlobalIndexProps(indexName: string) {
+    return this.table.options.getGlobalIndexProps(indexName);
+  }
+
+  /** Returns composed index keys. */
+  static composeIndexKeys(attributes: ItemAttributes) {
+    const idPrefix = this.idPrefix;
+    const documentName = this.name;
+    const tableOptions = this.table.options;
+
+    return composeIndexKeys({
+      idPrefix,
+      attributes,
+      documentName,
+      tableOptions,
+    });
+  }
+
+  /** Implements the interface to save a document, throws an error if document exists. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static async _create<T>(attributes: T, _context: Context): Promise<void> {
+    got(attributes, this.idKey, ATTRIBUTE_ERROR_TEMPLATE);
+    got(attributes, this.partitionKey, ATTRIBUTE_ERROR_TEMPLATE);
+
+    const indexKeys = this.composeIndexKeys(attributes as ItemAttributes);
+
+    const itemAttributes = cloneDeep({ ...indexKeys, ...attributes }) as ItemAttributes;
+
+    const isCreated = await this.table.createItem(itemAttributes);
+    const isDocumentExistsError = !isCreated;
+
+    if (isDocumentExistsError) {
+      throw new DocumentExistsError(this, itemAttributes);
+    }
+  }
+
+  /** Implements the interface to read a document. */
+  static async _read<T>(query: QueryMap): Promise<T> {
+    got(query, this.idKey, QUERY_ERROR_TEMPLATE);
+    got(query, this.partitionKey, ATTRIBUTE_ERROR_TEMPLATE);
+
+    const item = await this.table.getItem(query) as T;
+
+    if (!item) {
+      throw new DocumentNotFoundError(this, query);
+    }
+
+    return cloneDeep(item);
+  }
+
+  /** Implements the interface to update a document. */
+  static async _update<T>(query: QueryMap, mutation: MutationMap, _context: Context, previousAttributes: T): Promise<T> {
+    got(query, this.idKey, QUERY_ERROR_TEMPLATE);
+    got(query, this.partitionKey, QUERY_ERROR_TEMPLATE);
+
+    const indexKeys = this.composeIndexKeys({ ...previousAttributes, ...mutation });
+
+    const item = await this.table.updateItem(query, { ...indexKeys, ...mutation });
+
+    if (!item) {
+      throw new DocumentNotFoundError(this, query);
+    }
+
+    return cloneDeep(item) as T;
+  }
+
+  /** Implements the interface to delete a document. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static async _delete<T>(query: QueryMap, _context: Context, _previousAttributes: T): Promise<void> {
+    got(query, this.idKey, QUERY_ERROR_TEMPLATE);
+    got(query, this.partitionKey, QUERY_ERROR_TEMPLATE);
+
+    const isDeleted = await this.table.deleteItem(query);
+    const isDocumentNotFoundError = !isDeleted;
+
+    if (isDocumentNotFoundError) {
+      throw new DocumentNotFoundError(this, query);
+    }
+  }
+
+  /** Returns query that ensures access to the documents collection only. */
+  static _getIndexQuery(query: QueryMap, { indexName }: { indexName?: string }): {
+    indexQuery: QueryMap,
+    indexName?: string
+  } {
+    const indexQuery = cloneDeep(query);
+
+    if (!indexName) {
+      indexQuery[`${this.idKey}:${SortExpressionKey.BW}`] = `${this.idPrefix}_`;
+
+      return { indexQuery, indexName };
+    }
+
+    const isLocalSecondaryIndex = this.isLocalSecondaryIndex(indexName);
+
+    if (isLocalSecondaryIndex) {
+      return { indexQuery, indexName };
+    }
+
+    const partitionKeyName = this.getGlobalIndexPartitionKeyName(indexName);
+    const partitionKey = get(indexQuery, partitionKeyName, QUERY_ERROR_TEMPLATE) as string;
+
+    set(indexQuery, partitionKeyName, `${this.idPrefix}#${partitionKey}`);
+    unset(indexQuery, this.partitionKey);
+
+    return { indexQuery, indexName };
+  }
+
+  /** Implements the interface to get documents in batches. */
+  static async _index<T>(query: QueryMap, options: IndexOptions): Promise<{
+    limit: number;
+    count: number;
+    items: T[];
+    lastEvaluatedKey?: string;
+  }> {
+    const sort = get(options, 'sort', this.indexDefaultSort);
+    const limit = get(options, 'limit', this.indexDefaultLimit);
+    const exclusiveStartKey = get(options, 'exclusiveStartKey');
+
+    const { indexQuery, indexName } = this._getIndexQuery(query, options);
+
+    const { items, count, lastEvaluatedKey } = await this.table.listItems(indexQuery, {
+      sort,
+      limit,
+      indexName,
+      exclusiveStartKey,
+    });
+
+    return {
+      items: items as T[],
+      limit,
+      count,
+      lastEvaluatedKey,
+    };
+  }
+
+  /** Implements the interface to get all documents. */
+  static async _indexAll<T>(
+    query: QueryMap,
+    options: IndexAllOptions
+  ): Promise<{
+    count: number;
+    items: T[];
+  }> {
+    let resultItems = [] as T[];
+    let exclusiveStartKey: string | undefined;
+
+    const limit = INDEX_ALL_LIMIT;
+    const indexOptions = { limit, ...options } as IndexOptions;
+
+    do {
+      if (exclusiveStartKey) {
+        indexOptions.exclusiveStartKey = exclusiveStartKey;
+      }
+
+      const { items, lastEvaluatedKey: nextExclusiveStartKey } =
+        await this._index(query, indexOptions);
+
+      resultItems = [ ...resultItems, ...(items as T[]) ];
+      exclusiveStartKey = nextExclusiveStartKey;
+
+    } while (exclusiveStartKey);
+
+    const count = resultItems.length;
+
+    return {
+      items: resultItems,
+      count
+    };
+  }
+}
+
+export default Document;

package/src/Document/DocumentWithHashId.ts

@@ -0,0 +1,85 @@
+import Hashids from 'hashids';
+import Document from './Document';
+import { get, set } from 'lodash';
+import { wait, DocumentExistsError, type QueryMap, type Context } from '@kravc/dos';
+
+const CHARACTER_SET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890';
+const DEFAULT_INDEX_NAME = 'lsi1';
+const DEFAULT_NUMBER_KEY = 'number';
+
+/** Document class that uses hash ID as id key. */
+class DocumentWithHashId<T> extends Document<T> {
+  /** Returns salt for hash ID method. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static getSalt<T>(_context: Context, _attributes: T): string {
+    return this.name;
+  };
+
+  /** Returns number key. */
+  static get numberKey() {
+    return DEFAULT_NUMBER_KEY;
+  }
+
+  /** Ensures index query without index name uses lsi1 to sort documents. */
+  static _getIndexQuery(query: QueryMap, { indexName }: { indexName?: string }) {
+    return indexName
+      ? super._getIndexQuery(query, { indexName })
+      : super._getIndexQuery(query, { indexName: DEFAULT_INDEX_NAME });
+  }
+
+  /** Returns number for the next document. */
+  static async _getNextDocumentNumber(context: Context) {
+    const query = {};
+    const options = { limit: 1, sort: this.indexDefaultSort };
+
+    const { objects: documents } = await this.index(context, query, options);
+    const [ previousDocument ] = documents;
+
+    if (!previousDocument) {
+      return 1;
+    }
+
+    const number = get(previousDocument.attributes, this.numberKey, 0 );
+
+    return number + 1;
+  }
+
+  /** Ensures creation of a document with generated ID. */
+  static async _create<T>(attributes: T, context: Context): Promise<void> {
+    let number = get(attributes, this.numberKey) as number | undefined;
+
+    if (!number) {
+      number = await this._getNextDocumentNumber(context);
+    }
+
+    const salt = this.getSalt(context, attributes);
+    const hashids = new Hashids(salt, 0, CHARACTER_SET);
+    const hashId = hashids.encode(number);
+
+    const id = `${this.idPrefix}${hashId}`;
+
+    set(attributes as Record<string, unknown>, this.numberKey, number);
+    set(attributes as Record<string, unknown>, this.idKey, id);
+
+    try {
+      await super._create(attributes, context);
+      return;
+
+    } catch (error) {
+      const isDocumentExistsError = error instanceof DocumentExistsError;
+
+      /* istanbul ignore next */
+      if (!isDocumentExistsError) {
+        throw error;
+      }
+    }
+
+    await wait(50);
+
+    set(attributes as Record<string, unknown>, this.numberKey, number! + 1);
+
+    return this._create(attributes, context);
+  }
+};
+
+export default DocumentWithHashId;