{"id":22880970,"url":"https://github.com/beermoneydev/nest-qldb","last_synced_at":"2025-05-07T02:42:54.147Z","repository":{"id":40435855,"uuid":"286431088","full_name":"BeerMoneyDev/nest-qldb","owner":"BeerMoneyDev","description":"Object Document Mapper connecting NestJS to QLDB Quantum Ledger Database","archived":false,"fork":false,"pushed_at":"2024-02-07T23:43:51.000Z","size":730,"stargazers_count":16,"open_issues_count":2,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T05:32:33.948Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BeerMoneyDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-10T09:24:51.000Z","updated_at":"2024-02-16T01:25:07.000Z","dependencies_parsed_at":"2023-01-29T15:15:39.901Z","dependency_job_id":"63483ef7-6c40-4ee0-bcee-c91914be27b5","html_url":"https://github.com/BeerMoneyDev/nest-qldb","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-qldb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-qldb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-qldb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-qldb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BeerMoneyDev","download_url":"https://codeload.github.com/BeerMoneyDev/nest-qldb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252802607,"owners_count":21806537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-13T17:28:51.392Z","updated_at":"2025-05-07T02:42:54.122Z","avatar_url":"https://github.com/BeerMoneyDev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003enest-qldb\u003c/h1\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://miro.medium.com/max/5392/1*OvyWCTfnELrR3amCINM7SQ.png\" width=\"320\" alt=\"QLDB Logo\" /\u003e\n  \u003cimg src=\"https://nestjs.com/img/logo_text.svg\" width=\"320\" alt=\"Nest Logo\" /\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eA \u003ca href=\"https://github.com/nestjs\"\u003eNestJS\u003c/a\u003e module wrapping Amazon's Quantum Ledger Database with clean dependency injection for auto-generated repsitory layers or simple query service layer.\u003c/strong\u003e\n\u003c/div\u003e\n\n# Features\n\n- Extends the `amazon-qldb-driver-nodejs` work to add ODM functionality for QLDB common in NestJS.\n- A simple dependency injection model with `NestQldbModule.forRoot()`, `NestQldbModule.forRootAsync()`.\n- Simple auto-generated CRUD repositories for models, injectable by `@InjectRepository(model)`.\n- Provides a `QldbQueryService` provider for a simple Dapper-inspired query layer.\n\n# How To Use\n\n## Install\n\n```bash\nnpm install --save nest-qldb\n```\n\n## Importing\n\n### NestQldbModule.forRoot()\n\n`NestQldbModule.forRoot()` is the simplest way to import the QLDB module and autowire `@QldbTable` decorators. We re-export the `QldbDriver` from `amazon-qldb-driver-nodejs`.\u003cbr/\u003e\n\u003cstrong\u003eNote\u003c/strong\u003e: It is necessary that the ledger be created before application initialization.\n\n```ts\n// app.module.ts\n\nimport { NestQldbModule, QldbDriver } from 'nest-qldb';\nimport { User } from './user.model.ts';\n\n@Module({\n  imports: [\n    NestQldbModule.forRoot({\n      qldbDriver: new QldbDriver('fake-ledger')\n      createTablesAndIndexes: true,\n      tables: [User],\n    }),\n  ],\n})\nclass AppRootModule {}\n```\n\n#### driver\n\n`qldbDriver` is the driver to manage connections to Amazon's Quantum Ledger Database.\n\n### NestQldbModule.forRootAsync()\n\n`NestQldbModule.forRootAsync()` allows for a `FactoryProvider` or `ValueProvider` dependency declaration to import our module. Note that `ExistingProvider` and `ClassProvider` are not yet supported.\n\n```ts\n// app.module.ts\nimport { NestQldbModule, QldbDriver } from 'nest-qldb';\nimport { ConfigModule, ConfigService } from '@nestjs/config';\nimport { User } from './user.model.ts';\n\n@Module({\n  imports: [\n    NestQldbModule.forRootAsync({\n      qldbDriver: {\n        useFactory: async (configService: ConfigService) =\u003e {\n          return new QldbDriver(configService.qldbLedgerName, {\n            credentials: fromIni({\n              profile: config.qldbProfileName,\n            }),\n          });\n        },\n        inject: [ConfigService],\n      },\n      createTablesAndIndexes: true,\n      tables: [User],\n    }),\n    ConfigModule.forRoot(),\n  ],\n})\nclass AppRootModule {}\n```\n\n## Registering Models Binds them to QLDB tables\n\n### Models\n\nModel classes are the shape of the data in your QLDB tables. The `@QldbTable()` decorator is used to register your model as a table in Quantum Ledger Database. \u003c/br\u003e\nYou can also define the tableName and indexes associated with that model. \u003cstrong\u003eNOTE\u003c/strong\u003e: You can only create index when tables are empty so in the module config.\nThere is config on the module to perform this action at startup createTablesAndIndexes, it gracefully handles tables/indexes already created, however, it'll cost you a few seconds on a cold start so it is advised to turn it off in a production serverless scenario. \u003cbr/\u003e\u003cstrong\u003eNOTE: Any id properties will be peeled off models before they are saved! `id` is reserved for the qldb documentid\u003c/strong\u003e\n\n#### With decorator\n\n```ts\n// user.model.ts\nimport { QldbTable } from 'nest-qldb';\n\n@QldbTable({\n  tableName: 'users',\n  tableIndexes: ['name', 'phoneNumber'],\n})\nclass User {\n  name: string;\n  dateOfBirth: Date;\n  email: string;\n  phoneNumber: string;\n}\n```\n\n##### tableName\n\nThis is the name of the collection stored in QLDB.\n\n##### tableIndexes\n\nThese indexes will be created upon table creation. You cannot create indexes after records are inserted, so be aware.\n\n##### useMetadataKey\n\n_Default:_ `true`\n\nThis declares whether the key field should be a value in the QLDB metadata object (`true`), or a part of the data object (`false`).\n\n##### keyField\n\n_Default:_ `id`\n\nThis declares the field that will be used as the key.\n\n## Repository injection\n\nRepositories can be injected using the `@InjectRepository()` decorator. The repositories are created by `nest-qldb` and are a simple CRUD interface handy for quickly creating REST controllers.\n\n- `query(query QldbQuery)` - Performs Partiql query against table.\n- `create(data: T)` - Adds an object to the QLDB table\n- `retrieve(id: string)` - Fetches a single document by it's QLDB assigned id.\n- `replace(id: string, data: T)` - Replaces an entire document based on the id.\n- `destroy(id: string)` - Deletes an object from the table but not its change history from the ledger.\n- `history(id: string)` - Fetches all versions of a document across history\n- `createMany(data: T[])` - Will save many records in transactional batches of 40.\n\n```ts\n@Controller()\nclass UserController {\n  constructor(\n    @InjectRepository(User) readonly usersRepository: Repository\u003cUser\u003e,\n  ) {}\n\n  @Get(':id')\n  async getById(id: string) {\n    return await this.usersRepository.retrieve(id);\n  }\n}\n```\n\n## QldbQueryService\n\nThe `QldbQueryService` provider exposes simple methods that query and map the object to plain JSON objects.\n\n- `query` - Performs a query returning a list of rows mapped to a plain JSON object.\n- `querySingle` - Performs a query returning a single row mapped to a plain JSON object.\n- `queryForSubdocument` - Performs a query returning a list of nested documents in rows mapped to a plain JSON object.\n- `querySingleForSubdocument` - Performs a query returning a nested documents in single row mapped to a plain JSON object.\n- `execute` - Performs a query that returns no results. Ideal for inserts, updates, and deletes.\n\n```ts\nimport { Injectable } from '@nestjs/common';\nimport { QldbQueryService } from 'nest-qldb';\nimport { SearchResult } from './search.interfaces';\n\n@Injectable()\nclass UserService {\n  constructor(private readonly queryService: QldbQueryService) {}\n\n  async searchUsers(searchQuery: string) {\n    return await this.queryService.query\u003cSearchResult\u003e(\n      `\n      SELECT\n        id as userId,\n        u.name as userName,\n        u.email as userEmail\n      FROM users AS u BY id\n      WHERE LOWER(u.name) LIKE ?\n        OR LOWER(u.email) LIKE ?\n      `,\n      searchQuery?.toLocaleLowerCase(),\n    );\n  }\n}\n```\n\n# Stay In Touch\n\n- Author - [Benjamin Main](https://twitter.com/Ben05920582) and [BeerMoneyDev](https://www.beermoney.dev)\n\n## License\n\nnest-qldb is MIT licensed.\n\nSeveral core NestDependencies moved to peer dependencies to shrink package size.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeermoneydev%2Fnest-qldb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeermoneydev%2Fnest-qldb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeermoneydev%2Fnest-qldb/lists"}