{"id":20986820,"url":"https://github.com/karmaniverous/mock-db","last_synced_at":"2026-02-03T08:32:07.263Z","repository":{"id":255439067,"uuid":"850880104","full_name":"karmaniverous/mock-db","owner":"karmaniverous","description":"Mock DynamoDB-style query \u0026 scan behavior with local JSON data.","archived":false,"fork":false,"pushed_at":"2025-11-17T01:47:31.000Z","size":1527,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-17T03:25:22.748Z","etag":null,"topics":["dynamodb","json","mock","testing","typescript"],"latest_commit_sha":null,"homepage":"https://karmaniverous.github.io/mock-db","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karmaniverous.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["karmaniverous"]}},"created_at":"2024-09-02T02:20:19.000Z","updated_at":"2025-11-17T01:47:28.000Z","dependencies_parsed_at":"2024-11-09T06:21:59.317Z","dependency_job_id":"3f6cf15f-4243-4a01-aec3-1e829a5290cc","html_url":"https://github.com/karmaniverous/mock-db","commit_stats":null,"previous_names":["karmaniverous/mock-db"],"tags_count":20,"template":false,"template_full_name":"karmaniverous/npm-package-template-ts","purl":"pkg:github/karmaniverous/mock-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fmock-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fmock-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fmock-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fmock-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karmaniverous","download_url":"https://codeload.github.com/karmaniverous/mock-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fmock-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29038551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T06:39:36.383Z","status":"ssl_error","status_checked_at":"2026-02-03T06:39:32.787Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["dynamodb","json","mock","testing","typescript"],"created_at":"2024-11-19T06:15:00.004Z","updated_at":"2026-02-03T08:32:07.256Z","avatar_url":"https://github.com/karmaniverous.png","language":"TypeScript","funding_links":["https://github.com/sponsors/karmaniverous"],"categories":[],"sub_categories":[],"readme":"# @karmaniverous/mock-db\n\n[![npm version](https://img.shields.io/npm/v/@karmaniverous/mock-db.svg)](https://www.npmjs.com/package/@karmaniverous/mock-db) ![Node Current](https://img.shields.io/node/v/@karmaniverous/mock-db) \u003c!-- TYPEDOC_EXCLUDE --\u003e [![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/stan) [![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/mock-db/tree/main/CHANGELOG.md)\u003c!-- /TYPEDOC_EXCLUDE --\u003e [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/mock-db/tree/main/LICENSE.md)\n\nMockDb is a tiny, test‑oriented helper that simulates a small subset of\nAmazon DynamoDB behaviors over an in‑memory array of JSON objects. Its goal is\nto make it easy to unit/integration test code that expects “Dynamo‑like”\nreads without needing to provision a real database.\n\nWhat you get:\n\n- querySync and query — scan across all items or query a partition (hash key)\n- Optional sorting, filtering, limits, and pagination (pageKey)\n- Sync and async flavors (async returns with a normally‑distributed delay)\n\nWhat you do NOT get:\n\n- A database. This is a small helper for tests, not a general data store.\n- The full DynamoDB API. Only a small, ergonomic subset of behavior.\n\nMockDb uses [@karmaniverous/entity-tools](https://github.com/karmaniverous/entity-tools)\nfor type modeling and sorting.\n\n## Installation\n\nYou’ll typically install this as a dev dependency:\n\n```bash\nnpm i -D @karmaniverous/mock-db\n```\n\nNode: \u003e= 18 recommended (ESM module). The package ships both ESM and CJS outputs.\n\n## Quick start\n\n```ts\nimport type { Entity } from '@karmaniverous/mock-db'; // convenience re-export\nimport { MockDb, type QueryOptions } from '@karmaniverous/mock-db';\n\ninterface User extends Entity {\n  partition: string; // hash key\n  id: number;\n  name: string;\n}\n\nconst users: User[] = [\n  { partition: 'a', id: 4, name: 'Alice' },\n  { partition: 'b', id: 3, name: 'Bob' },\n  { partition: 'a', id: 2, name: 'Charlie' },\n  { partition: 'a', id: 1, name: 'Dave' },\n];\n\nconst db = new MockDb(users); // default async mean=100ms, std=20ms\n\n// 1) Synchronous “scan” across all items with filter + sort\nconst scan = db.querySync({\n  filter: ({ id }) =\u003e id \u003e 2,\n  sortOrder: [{ property: 'id' }],\n});\n// =\u003e { count: 2, items: [...], pageKey: undefined }\n\n// 2) Asynchronous, paged, sorted “query” within a partition (hash key)\nconst opts: QueryOptions\u003cUser\u003e = {\n  hashKey: 'partition',\n  hashValue: 'a',\n  indexComponents: ['partition', 'id'],\n  limit: 2,\n  sortOrder: [{ property: 'id' }],\n};\n\nlet page = await db.query(opts, 100);\n// =\u003e first two items plus pageKey for next page\n\npage = await db.query({ ...opts, pageKey: page.pageKey }, 100);\n// =\u003e next page (remaining items)\n```\n\nCommonJS example:\n\n```js\nconst { MockDb } = require('@karmaniverous/mock-db');\n```\n\n## API overview\n\n### class MockDb\u003cE extends Entity, T extends TranscodeRegistry = DefaultTranscodeRegistry\u003e\n\nReplicates a limited set of DynamoDB scan/query behaviors over a local array.\n\nConstructor\n\n- new MockDb(data: E[], delayMean = 100, delayStd = 20)\n  - delayMean/delayStd (ms) control async delay for query(...). querySync is always synchronous.\n\nMethods\n\n- querySync(options?: QueryOptions\u003cE, T\u003e): QueryReturn\u003cE, T\u003e\n- query(options?: QueryOptions\u003cE, T\u003e, delayMean?: number, delayStd?: number): Promise\u003cQueryReturn\u003cE, T\u003e\u003e\n\n### type QueryOptions\u003cE, T\u003e\n\nOptions for query/querySync (T is a TranscodeRegistry):\n\n- hashKey?: TranscodableProperties\u003cE, T\u003e  \n  When provided with hashValue, restricts results to the “partition” (like DynamoDB query).\n- hashValue?: T[keyof T]\n- sortOrder?: SortOrder\u003cE\u003e  \n  Sorting keys and directions; powered by entity‑tools’ sort.\n- filter?: (item: E) =\u003e unknown  \n  Predicate to include items.\n- limit?: number  \n  Maximum number of items to return.\n- pageKey?: E | Partial\u003cPick\u003cE, TranscodableProperties\u003cE, T\u003e\u003e\u003e  \n  If set, results begin after this item (pagination).\n- indexComponents?: TranscodableProperties\u003cE, T\u003e[]  \n  When limit is reached, the returned pageKey contains only these properties; otherwise it will be the entire last item.\n\n### type QueryReturn\u003cE, T\u003e\n\nResult from query/querySync:\n\n- count: number  \n  Count of items returned in this page (not the entire dataset).\n- items: E[]  \n  The data items in this page.\n- pageKey?: E | Pick\u003cE, TranscodableProperties\u003cE, T\u003e\u003e  \n  Present when limit was reached; pass back as options.pageKey to get the next page.\n\n### Behavior notes\n\n- Scan vs Query:\n  - If hashKey + hashValue are omitted, behavior is a “scan” across all items.\n  - If both are present, behavior is a “query” restricted to that partition.\n- Sorting: Applied before pagination/filtering (like Dynamo’s sorted result sets).\n- Filtering: A plain predicate function; no Dynamo expression syntax.\n- Pagination: Provide limit; when the page is full, the last item’s indexComponents (or the entire item) is returned as pageKey. Pass it back to get the next page.\n- Async timing: query(...) simulates network latency with a normal distribution around delayMean (std delayStd). querySync(...) performs the same logic without delay.\n\n## Re‑exported convenience types\n\nTo avoid a direct dependency on @karmaniverous/entity‑tools in your imports, the following types are re‑exported:\n\n```ts\nimport type {\n  Entity,\n  SortOrder,\n  TranscodeRegistry,\n  DefaultTranscodeRegistry,\n} from '@karmaniverous/mock-db';\n```\n\nYou can still import them from @karmaniverous/entity‑tools if you prefer.\n\n## Project scripts (local)\n\n- Test: `npm test` (Vitest; coverage via V8)\n- Lint/format: `npm run lint` (ESLint) • `npm run lint:fix` (ESLint + Prettier)\n- Typecheck: `npm run typecheck` (tsc, no emit)\n- Build: `npm run build` (Rollup – ESM/CJS + dts)\n- Docs: `npm run docs` (TypeDoc)\n\n## Typedocs\n\nSee the online [API Documentation](https://docs.karmanivero.us/mock-db) for the complete, generated API reference.\n\n## Why not a real database?\n\nThis library is meant for fast, deterministic test runs where mocking a small\nsubset of Dynamo behaviors is sufficient (hash key filtering, sorting,\npagination). If you need to exercise full DynamoDB semantics, consider running\na local emulator or integration tests against a real service.\n\n---\n\nBuilt for you with ❤️ on Bali! Find more tools \u0026 templates on\n[my GitHub Profile](https://github.com/karmaniverous).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarmaniverous%2Fmock-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarmaniverous%2Fmock-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarmaniverous%2Fmock-db/lists"}