https://github.com/karmaniverous/mock-db
Mock DynamoDB-style query & scan behavior with local JSON data.
https://github.com/karmaniverous/mock-db
dynamodb json mock testing typescript
Last synced: 5 months ago
JSON representation
Mock DynamoDB-style query & scan behavior with local JSON data.
- Host: GitHub
- URL: https://github.com/karmaniverous/mock-db
- Owner: karmaniverous
- Created: 2024-09-02T02:20:19.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-11-17T01:47:31.000Z (8 months ago)
- Last Synced: 2025-11-17T03:25:22.748Z (8 months ago)
- Topics: dynamodb, json, mock, testing, typescript
- Language: TypeScript
- Homepage: https://karmaniverous.github.io/mock-db
- Size: 1.46 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# @karmaniverous/mock-db
[](https://www.npmjs.com/package/@karmaniverous/mock-db)  [](https://docs.karmanivero.us/stan) [](https://github.com/karmaniverous/mock-db/tree/main/CHANGELOG.md) [](https://github.com/karmaniverous/mock-db/tree/main/LICENSE.md)
MockDb is a tiny, test‑oriented helper that simulates a small subset of
Amazon DynamoDB behaviors over an in‑memory array of JSON objects. Its goal is
to make it easy to unit/integration test code that expects “Dynamo‑like”
reads without needing to provision a real database.
What you get:
- querySync and query — scan across all items or query a partition (hash key)
- Optional sorting, filtering, limits, and pagination (pageKey)
- Sync and async flavors (async returns with a normally‑distributed delay)
What you do NOT get:
- A database. This is a small helper for tests, not a general data store.
- The full DynamoDB API. Only a small, ergonomic subset of behavior.
MockDb uses [@karmaniverous/entity-tools](https://github.com/karmaniverous/entity-tools)
for type modeling and sorting.
## Installation
You’ll typically install this as a dev dependency:
```bash
npm i -D @karmaniverous/mock-db
```
Node: >= 18 recommended (ESM module). The package ships both ESM and CJS outputs.
## Quick start
```ts
import type { Entity } from '@karmaniverous/mock-db'; // convenience re-export
import { MockDb, type QueryOptions } from '@karmaniverous/mock-db';
interface User extends Entity {
partition: string; // hash key
id: number;
name: string;
}
const users: User[] = [
{ partition: 'a', id: 4, name: 'Alice' },
{ partition: 'b', id: 3, name: 'Bob' },
{ partition: 'a', id: 2, name: 'Charlie' },
{ partition: 'a', id: 1, name: 'Dave' },
];
const db = new MockDb(users); // default async mean=100ms, std=20ms
// 1) Synchronous “scan” across all items with filter + sort
const scan = db.querySync({
filter: ({ id }) => id > 2,
sortOrder: [{ property: 'id' }],
});
// => { count: 2, items: [...], pageKey: undefined }
// 2) Asynchronous, paged, sorted “query” within a partition (hash key)
const opts: QueryOptions = {
hashKey: 'partition',
hashValue: 'a',
indexComponents: ['partition', 'id'],
limit: 2,
sortOrder: [{ property: 'id' }],
};
let page = await db.query(opts, 100);
// => first two items plus pageKey for next page
page = await db.query({ ...opts, pageKey: page.pageKey }, 100);
// => next page (remaining items)
```
CommonJS example:
```js
const { MockDb } = require('@karmaniverous/mock-db');
```
## API overview
### class MockDb
Replicates a limited set of DynamoDB scan/query behaviors over a local array.
Constructor
- new MockDb(data: E[], delayMean = 100, delayStd = 20)
- delayMean/delayStd (ms) control async delay for query(...). querySync is always synchronous.
Methods
- querySync(options?: QueryOptions): QueryReturn
- query(options?: QueryOptions, delayMean?: number, delayStd?: number): Promise>
### type QueryOptions
Options for query/querySync (T is a TranscodeRegistry):
- hashKey?: TranscodableProperties
When provided with hashValue, restricts results to the “partition” (like DynamoDB query).
- hashValue?: T[keyof T]
- sortOrder?: SortOrder
Sorting keys and directions; powered by entity‑tools’ sort.
- filter?: (item: E) => unknown
Predicate to include items.
- limit?: number
Maximum number of items to return.
- pageKey?: E | Partial>>
If set, results begin after this item (pagination).
- indexComponents?: TranscodableProperties[]
When limit is reached, the returned pageKey contains only these properties; otherwise it will be the entire last item.
### type QueryReturn
Result from query/querySync:
- count: number
Count of items returned in this page (not the entire dataset).
- items: E[]
The data items in this page.
- pageKey?: E | Pick>
Present when limit was reached; pass back as options.pageKey to get the next page.
### Behavior notes
- Scan vs Query:
- If hashKey + hashValue are omitted, behavior is a “scan” across all items.
- If both are present, behavior is a “query” restricted to that partition.
- Sorting: Applied before pagination/filtering (like Dynamo’s sorted result sets).
- Filtering: A plain predicate function; no Dynamo expression syntax.
- 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.
- Async timing: query(...) simulates network latency with a normal distribution around delayMean (std delayStd). querySync(...) performs the same logic without delay.
## Re‑exported convenience types
To avoid a direct dependency on @karmaniverous/entity‑tools in your imports, the following types are re‑exported:
```ts
import type {
Entity,
SortOrder,
TranscodeRegistry,
DefaultTranscodeRegistry,
} from '@karmaniverous/mock-db';
```
You can still import them from @karmaniverous/entity‑tools if you prefer.
## Project scripts (local)
- Test: `npm test` (Vitest; coverage via V8)
- Lint/format: `npm run lint` (ESLint) • `npm run lint:fix` (ESLint + Prettier)
- Typecheck: `npm run typecheck` (tsc, no emit)
- Build: `npm run build` (Rollup – ESM/CJS + dts)
- Docs: `npm run docs` (TypeDoc)
## Typedocs
See the online [API Documentation](https://docs.karmanivero.us/mock-db) for the complete, generated API reference.
## Why not a real database?
This library is meant for fast, deterministic test runs where mocking a small
subset of Dynamo behaviors is sufficient (hash key filtering, sorting,
pagination). If you need to exercise full DynamoDB semantics, consider running
a local emulator or integration tests against a real service.
---
Built for you with ❤️ on Bali! Find more tools & templates on
[my GitHub Profile](https://github.com/karmaniverous).