@decohere/data-memory 0.0.0-stage → 0.0.1-dev.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -2
- package/package.json +36 -4
- package/src/index.ts +4 -0
- package/src/memory-entity.ts +150 -0
- package/src/memory.plugin.ts +63 -0
- package/src/memory.row-store.ts +87 -0
- package/src/memory.store.ts +508 -0
- package/tests/memory.plugin.spec.ts +100 -0
- package/tests/memory.store.spec.ts +157 -0
- package/tests/model.ts +39 -0
package/README.md
CHANGED
|
@@ -1,3 +1,53 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @decohere/data-memory
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The in-memory provider for [`@decohere/data`](../data/README.md): the same repositories and unit of work as on a database, with the rows held in the process. For tests and local runs that shouldn't need Postgres. The unit of work is data's `TrackingUnitOfWork`, as on [TypeORM](../data-typeorm/README.md), over a `MemoryRowStore`. The contract suite's cases run on it in `pnpm test`, with no Docker.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
builder.use(
|
|
7
|
+
memory({
|
|
8
|
+
entities: [
|
|
9
|
+
mapEntity(Order, {
|
|
10
|
+
fields: ["customer", "note", "status", "placedAt"],
|
|
11
|
+
version: "version",
|
|
12
|
+
children: [{ prop: "lines", target: Line, parentRef: "order" }],
|
|
13
|
+
}),
|
|
14
|
+
mapEntity(Line, {
|
|
15
|
+
fields: ["sku", "quantity"],
|
|
16
|
+
references: [{ prop: "order", target: Order }],
|
|
17
|
+
}),
|
|
18
|
+
],
|
|
19
|
+
repositories: [OrderRepository],
|
|
20
|
+
outbox: toOutboxMessage,
|
|
21
|
+
seed: async (uow) => uow.add(new Order("demo")),
|
|
22
|
+
}),
|
|
23
|
+
);
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Swapping it for `typeOrm(…)` or `mikroOrm(…)` changes this line and the mappings, not the repositories. It needs no `database` config, connects to nothing and has nothing to migrate, so the `db` commands find no data source on it. Each build of the app starts with empty stores, so two apps, or two tests, never share rows. With `seed`, the app's start step adds the rows, in a unit of work committed when it returns.
|
|
27
|
+
|
|
28
|
+
## Mapping
|
|
29
|
+
|
|
30
|
+
There's no ORM to read a mapping from, so each class is mapped with `mapEntity(type, options)`:
|
|
31
|
+
|
|
32
|
+
| Option | Means |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| `key` | The properties making the key: fields or references. Defaults to `["id"]`. |
|
|
35
|
+
| `fields` | The properties stored as values. Key fields, the version and the generated key may be left out. |
|
|
36
|
+
| `references` | `{ prop, target, nullable?, onDelete? }`: a property holding another mapped entity, stored as its key. Required unless `nullable`. `onDelete: "cascade"` deletes this row with the one it references. Otherwise that delete fails while this row references it. |
|
|
37
|
+
| `children` | `{ prop, target, parentRef, orderBy? }`: a `Children<T>` collection, the rows of `target` whose `parentRef` references this one. |
|
|
38
|
+
| `version` | A number checked and incremented on every update. |
|
|
39
|
+
| `generated` | A key field numbered 1, 2, 3… when an insert leaves it empty, like a serial column. |
|
|
40
|
+
|
|
41
|
+
The mapping is checked when the app is built, so a reference to a class that isn't mapped fails then.
|
|
42
|
+
|
|
43
|
+
## What it keeps from a database
|
|
44
|
+
|
|
45
|
+
It behaves as Postgres does wherever a repository could tell the difference:
|
|
46
|
+
|
|
47
|
+
- **Keys and foreign keys.** A second row with the same key fails. So does a reference to a row that doesn't exist, an empty required reference, or deleting a row that something still references (unless the reference cascades).
|
|
48
|
+
- **Transactions.** A unit of work's writes stay its own until it commits, and are applied all together. Reads see what is committed plus their own writes. A statement that fails aborts the transaction, which can then only roll back.
|
|
49
|
+
- **Row locks.** These take Postgres's modes: `lock: "update"` and deletes lock the row, updates lock it against other updates, and a reference locks the row it points at against deletion. A second unit of work waits for the first to commit or roll back, then reads the row as it is. Two that would wait for each other fail one of them with a deadlock error.
|
|
50
|
+
- **Copies.** Rows are copied in and out, so an object held outside the unit of work can't change what is stored.
|
|
51
|
+
- **SQL's nulls.** An empty value matches only `null` and `{ ne: … }` with a value given. It sorts last ascending and first descending.
|
|
52
|
+
|
|
53
|
+
What differs: strings compare and sort by code unit, not by the database's collation. Columns have no types, lengths or `NOT NULL` checks beyond the key and required references. And the rows last only as long as the app.
|
package/package.json
CHANGED
|
@@ -1,6 +1,38 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@decohere/data-memory",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.1-dev.5",
|
|
4
|
+
"description": "In-memory provider for @decohere/data: repositories and the unit of work with no database, for tests and local runs",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"typescript",
|
|
7
|
+
"in-memory",
|
|
8
|
+
"testing",
|
|
9
|
+
"data-access",
|
|
10
|
+
"decohere"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://github.com/typesmiths/decohere/tree/main/projects/data/data-memory#readme",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/typesmiths/decohere/issues"
|
|
15
|
+
},
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/typesmiths/decohere.git",
|
|
19
|
+
"directory": "projects/data/data-memory"
|
|
20
|
+
},
|
|
21
|
+
"license": "ISC",
|
|
22
|
+
"author": "Typesmiths",
|
|
23
|
+
"type": "module",
|
|
24
|
+
"exports": {
|
|
25
|
+
".": {
|
|
26
|
+
"types": "./types/src/index.d.ts",
|
|
27
|
+
"import": "./es6/src/index.js"
|
|
28
|
+
}
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"test": "echo \"Error: no test specified\" && exit 1"
|
|
32
|
+
},
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"@decohere/core": "0.0.1-dev.5",
|
|
35
|
+
"@decohere/data": "0.0.1-dev.5"
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {}
|
|
38
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type ChildKeys,
|
|
3
|
+
type ChildrenModel,
|
|
4
|
+
DataConfigurationError,
|
|
5
|
+
type EntityClass,
|
|
6
|
+
type EntityModel,
|
|
7
|
+
type FieldKeys,
|
|
8
|
+
type ReferenceModel,
|
|
9
|
+
} from "@decohere/data";
|
|
10
|
+
|
|
11
|
+
/** A reference to another mapped class, stored as that class's key. */
|
|
12
|
+
export type MemoryReference<T> = {
|
|
13
|
+
prop: FieldKeys<T>;
|
|
14
|
+
target: EntityClass;
|
|
15
|
+
/** Whether it may be empty. Defaults to false: a row can't be written without it. */
|
|
16
|
+
nullable?: boolean;
|
|
17
|
+
/** `"cascade"`: deleting the referenced row deletes this one, like `ON DELETE CASCADE`. Otherwise the delete fails while this row references it. */
|
|
18
|
+
onDelete?: "cascade";
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
/** A child collection: the rows of `target` whose `parentRef` references this one. */
|
|
22
|
+
export type MemoryChildren<T> = {
|
|
23
|
+
prop: ChildKeys<T>;
|
|
24
|
+
target: EntityClass;
|
|
25
|
+
/** The child's reference to its parent. */
|
|
26
|
+
parentRef: string;
|
|
27
|
+
/** The order children load in. Defaults to the child's key, ascending. */
|
|
28
|
+
orderBy?: Record<string, "asc" | "desc">;
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
export type MemoryEntityOptions<T> = {
|
|
32
|
+
/** The properties making the key: fields or references. Defaults to `["id"]`. */
|
|
33
|
+
key?: FieldKeys<T>[];
|
|
34
|
+
/** The properties stored as values. Key fields, the version and the generated key may be left out. */
|
|
35
|
+
fields: FieldKeys<T>[];
|
|
36
|
+
references?: MemoryReference<T>[];
|
|
37
|
+
children?: MemoryChildren<T>[];
|
|
38
|
+
/** A number checked and incremented on every update. */
|
|
39
|
+
version?: FieldKeys<T>;
|
|
40
|
+
/** A key field the store numbers 1, 2, 3… when an insert leaves it empty, like a serial column. */
|
|
41
|
+
generated?: FieldKeys<T>;
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/** One class's mapping, as {@link mapEntity} makes it. */
|
|
45
|
+
export type MemoryEntity = EntityModel & {
|
|
46
|
+
references: (ReferenceModel & { onDelete?: "cascade" })[];
|
|
47
|
+
generated?: string;
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Map a class for the memory provider. With no ORM to read metadata from, the mapping is written
|
|
52
|
+
* out: which properties are stored, which reference another class, and which hold children.
|
|
53
|
+
*/
|
|
54
|
+
export function mapEntity<T extends object>(
|
|
55
|
+
type: EntityClass<T>,
|
|
56
|
+
options: MemoryEntityOptions<T>,
|
|
57
|
+
): MemoryEntity {
|
|
58
|
+
const key: string[] = options.key ?? ["id"];
|
|
59
|
+
const references = (options.references ?? []).map((r) => ({
|
|
60
|
+
prop: r.prop,
|
|
61
|
+
target: r.target,
|
|
62
|
+
nullable: r.nullable ?? false,
|
|
63
|
+
onDelete: r.onDelete,
|
|
64
|
+
}));
|
|
65
|
+
const isReference = (prop: string) => references.some((r) => r.prop === prop);
|
|
66
|
+
const fields = new Set<string>(options.fields);
|
|
67
|
+
for (const prop of key) if (!isReference(prop)) fields.add(prop);
|
|
68
|
+
if (options.version) fields.add(options.version);
|
|
69
|
+
if (options.generated) fields.add(options.generated);
|
|
70
|
+
return {
|
|
71
|
+
type,
|
|
72
|
+
name: type.name,
|
|
73
|
+
key,
|
|
74
|
+
fields: [...fields],
|
|
75
|
+
references,
|
|
76
|
+
children: (options.children ?? []).map((c): ChildrenModel => ({
|
|
77
|
+
prop: c.prop,
|
|
78
|
+
target: c.target,
|
|
79
|
+
parentRef: c.parentRef,
|
|
80
|
+
orderBy: c.orderBy,
|
|
81
|
+
})),
|
|
82
|
+
version: options.version,
|
|
83
|
+
generated: options.generated,
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Check the mappings fit together, so a mistake fails when the app is built rather than at the
|
|
89
|
+
* first query: every key, reference and child names something mapped.
|
|
90
|
+
*/
|
|
91
|
+
function check(entities: readonly MemoryEntity[]): Map<EntityClass, MemoryEntity> {
|
|
92
|
+
const byType = new Map<EntityClass, MemoryEntity>();
|
|
93
|
+
for (const entity of entities) {
|
|
94
|
+
if (byType.has(entity.type)) {
|
|
95
|
+
throw new DataConfigurationError(`${entity.name} is mapped twice`);
|
|
96
|
+
}
|
|
97
|
+
byType.set(entity.type, entity);
|
|
98
|
+
}
|
|
99
|
+
const mapped = (owner: MemoryEntity, prop: string, target: EntityClass) => {
|
|
100
|
+
const found = byType.get(target);
|
|
101
|
+
if (found == null) {
|
|
102
|
+
throw new DataConfigurationError(
|
|
103
|
+
`${owner.name}.${prop} points at ${target.name}, which isn't mapped: add it to entities`,
|
|
104
|
+
);
|
|
105
|
+
}
|
|
106
|
+
return found;
|
|
107
|
+
};
|
|
108
|
+
for (const entity of entities) {
|
|
109
|
+
const { name } = entity;
|
|
110
|
+
const isReference = (prop: string) => entity.references.some((r) => r.prop === prop);
|
|
111
|
+
if (entity.key.length === 0) {
|
|
112
|
+
throw new DataConfigurationError(`${name} has no key`);
|
|
113
|
+
}
|
|
114
|
+
if (entity.generated && (entity.key.length !== 1 || entity.key[0] !== entity.generated)) {
|
|
115
|
+
throw new DataConfigurationError(
|
|
116
|
+
`${name}.${entity.generated} is generated, so it must be the whole key`,
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
for (const ref of entity.references) {
|
|
120
|
+
if (entity.fields.includes(ref.prop)) {
|
|
121
|
+
throw new DataConfigurationError(
|
|
122
|
+
`${name}.${ref.prop} is both a field and a reference`,
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
const target = mapped(entity, ref.prop, ref.target);
|
|
126
|
+
if (target.key.length !== 1) {
|
|
127
|
+
throw new DataConfigurationError(
|
|
128
|
+
`${name}.${ref.prop} references ${target.name}, whose key is composite: a reference must point at a single key`,
|
|
129
|
+
);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
for (const spec of entity.children) {
|
|
133
|
+
const child = mapped(entity, spec.prop, spec.target);
|
|
134
|
+
const parentRef = child.references.find((r) => r.prop === spec.parentRef);
|
|
135
|
+
if (parentRef == null || parentRef.target !== entity.type) {
|
|
136
|
+
throw new DataConfigurationError(
|
|
137
|
+
`${name}.${spec.prop}: ${child.name}.${spec.parentRef} must be a reference to ${name}`,
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
for (const prop of entity.key) {
|
|
142
|
+
if (!entity.fields.includes(prop) && !isReference(prop)) {
|
|
143
|
+
throw new DataConfigurationError(`${name}'s key ${prop} isn't mapped`);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
return byType;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
export const memoryEntities = { check };
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import type { BuilderPlugin } from "@decohere/core/hosting";
|
|
2
|
+
import type { Constructable } from "@decohere/core/reflection";
|
|
3
|
+
import {
|
|
4
|
+
DataConfigurationError,
|
|
5
|
+
DEFAULT_DATA_SOURCE,
|
|
6
|
+
type IUnitOfWork,
|
|
7
|
+
type OutboxMapper,
|
|
8
|
+
TrackingUnitOfWork,
|
|
9
|
+
} from "@decohere/data";
|
|
10
|
+
import type { MemoryEntity } from "./memory-entity.js";
|
|
11
|
+
import { MemoryRowStore } from "./memory.row-store.js";
|
|
12
|
+
import { MemoryStore } from "./memory.store.js";
|
|
13
|
+
|
|
14
|
+
export type MemoryModuleConfig = {
|
|
15
|
+
/** The data source's name, as `@injectUnitOfWork(name)` asks for it. Required when there are several. */
|
|
16
|
+
name?: string;
|
|
17
|
+
/** Each mapped class: `mapEntity(Order, { … })`. */
|
|
18
|
+
entities: MemoryEntity[];
|
|
19
|
+
repositories?: Constructable[];
|
|
20
|
+
/** Writes the events aggregates raise to an outbox entity, in the same commit. */
|
|
21
|
+
outbox?: OutboxMapper;
|
|
22
|
+
/** Runs when the app starts, with a unit of work that is committed when it returns. */
|
|
23
|
+
seed?: (unitOfWork: IUnitOfWork) => Promise<void>;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Keep the data in the process, with no database: for tests and local runs. Each build of the app
|
|
28
|
+
* gets empty stores of its own. Needs no `database` config.
|
|
29
|
+
*/
|
|
30
|
+
export function memory(config: MemoryModuleConfig[] | MemoryModuleConfig): BuilderPlugin {
|
|
31
|
+
const modules = Array.isArray(config) ? config : [config];
|
|
32
|
+
if (modules.length > 1 && modules.some((m) => m.name == null)) {
|
|
33
|
+
throw new DataConfigurationError("Name is required if there is more than one datasource");
|
|
34
|
+
}
|
|
35
|
+
return (builder) => {
|
|
36
|
+
const stores = new Map<MemoryModuleConfig, MemoryStore>();
|
|
37
|
+
builder.withServices((containerBuilder) => {
|
|
38
|
+
for (const module of modules) {
|
|
39
|
+
const store = new MemoryStore(module.entities);
|
|
40
|
+
stores.set(module, store);
|
|
41
|
+
containerBuilder.registerRequestScoped(
|
|
42
|
+
module.name ?? DEFAULT_DATA_SOURCE,
|
|
43
|
+
() => new TrackingUnitOfWork(new MemoryRowStore(store), { outbox: module.outbox }),
|
|
44
|
+
);
|
|
45
|
+
for (const repository of module.repositories ?? []) {
|
|
46
|
+
containerBuilder.registerRequestScoped(repository);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
if (modules.every((m) => m.seed == null)) return;
|
|
51
|
+
builder.registerStartStep(async () => {
|
|
52
|
+
for (const module of modules) {
|
|
53
|
+
const store = stores.get(module);
|
|
54
|
+
if (module.seed == null || store == null) continue;
|
|
55
|
+
await using unitOfWork = new TrackingUnitOfWork(new MemoryRowStore(store), {
|
|
56
|
+
outbox: module.outbox,
|
|
57
|
+
});
|
|
58
|
+
await module.seed(unitOfWork);
|
|
59
|
+
await unitOfWork.commit();
|
|
60
|
+
}
|
|
61
|
+
}, "memory data sources");
|
|
62
|
+
};
|
|
63
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import {
|
|
2
|
+
DataError,
|
|
3
|
+
type EntityClass,
|
|
4
|
+
type EntityModel,
|
|
5
|
+
type Row,
|
|
6
|
+
type RowQuery,
|
|
7
|
+
type RowStore,
|
|
8
|
+
} from "@decohere/data";
|
|
9
|
+
import type { MemoryStore, MemoryTransaction } from "./memory.store.js";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The memory provider's share of the unit of work: one transaction at a time on a
|
|
13
|
+
* {@link MemoryStore}. Outside a transaction each operation runs in one of its own, as a database
|
|
14
|
+
* runs a statement on its own.
|
|
15
|
+
*/
|
|
16
|
+
export class MemoryRowStore implements RowStore {
|
|
17
|
+
private transaction: MemoryTransaction | undefined;
|
|
18
|
+
|
|
19
|
+
public constructor(private readonly store: MemoryStore) {}
|
|
20
|
+
|
|
21
|
+
public model(type: EntityClass): EntityModel {
|
|
22
|
+
return this.store.model(type);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
public async begin() {
|
|
26
|
+
if (this.transaction) throw new DataError("A transaction is already open");
|
|
27
|
+
this.transaction = this.store.begin();
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
public async commit() {
|
|
31
|
+
this.store.commit(this.end());
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
public async rollback() {
|
|
35
|
+
this.store.rollback(this.end());
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
public async release() {
|
|
39
|
+
if (this.transaction) await this.rollback();
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
public inTransaction() {
|
|
43
|
+
return this.transaction != null;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
public select(type: EntityClass, query: RowQuery): Promise<Row[]> {
|
|
47
|
+
return this.run((tx) => this.store.select(tx, type, query));
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
public insert(type: EntityClass, rows: Row[]): Promise<Row[]> {
|
|
51
|
+
return this.run((tx) => this.store.insert(tx, type, rows));
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
public update(
|
|
55
|
+
type: EntityClass,
|
|
56
|
+
key: Row,
|
|
57
|
+
changes: Row,
|
|
58
|
+
version?: { prop: string; expected: unknown },
|
|
59
|
+
): Promise<number> {
|
|
60
|
+
return this.run((tx) => this.store.update(tx, type, key, changes, version));
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
public delete(type: EntityClass, keys: Row[]): Promise<void> {
|
|
64
|
+
return this.run((tx) => this.store.delete(tx, type, keys));
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
private end(): MemoryTransaction {
|
|
68
|
+
const tx = this.transaction;
|
|
69
|
+
if (tx == null) throw new DataError("No transaction is open");
|
|
70
|
+
this.transaction = undefined;
|
|
71
|
+
return tx;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
private async run<R>(operation: (tx: MemoryTransaction) => Promise<R>): Promise<R> {
|
|
75
|
+
if (this.transaction) return operation(this.transaction);
|
|
76
|
+
const tx = this.store.begin();
|
|
77
|
+
let result: R;
|
|
78
|
+
try {
|
|
79
|
+
result = await operation(tx);
|
|
80
|
+
} catch (err) {
|
|
81
|
+
this.store.rollback(tx);
|
|
82
|
+
throw err;
|
|
83
|
+
}
|
|
84
|
+
this.store.commit(tx);
|
|
85
|
+
return result;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
@@ -0,0 +1,508 @@
|
|
|
1
|
+
import {
|
|
2
|
+
comparison,
|
|
3
|
+
type Comparison,
|
|
4
|
+
DataConfigurationError,
|
|
5
|
+
DataError,
|
|
6
|
+
type EntityClass,
|
|
7
|
+
type Row,
|
|
8
|
+
type RowQuery,
|
|
9
|
+
} from "@decohere/data";
|
|
10
|
+
import { type MemoryEntity, memoryEntities } from "./memory-entity.js";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Row locks, as Postgres takes them: a reference check takes `key-share` on the row it points at,
|
|
14
|
+
* an update that keeps the key takes `no-key-update`, and a delete, a key change or
|
|
15
|
+
* `lock: "update"` takes `update`. Each blocks only the modes Postgres says it conflicts with.
|
|
16
|
+
*/
|
|
17
|
+
type LockMode = "key-share" | "no-key-update" | "update";
|
|
18
|
+
|
|
19
|
+
const CONFLICTS: Record<LockMode, readonly LockMode[]> = {
|
|
20
|
+
"key-share": ["update"],
|
|
21
|
+
"no-key-update": ["no-key-update", "update"],
|
|
22
|
+
update: ["key-share", "no-key-update", "update"],
|
|
23
|
+
};
|
|
24
|
+
const STRENGTH: Record<LockMode, number> = { "key-share": 0, "no-key-update": 1, update: 2 };
|
|
25
|
+
|
|
26
|
+
/** One transaction: its writes, kept apart until commit, and the row locks it holds. */
|
|
27
|
+
export class MemoryTransaction {
|
|
28
|
+
/** Per class, by key: the row as this transaction wrote it, or null where it deleted one. */
|
|
29
|
+
public readonly writes = new Map<EntityClass, Map<string, Row | null>>();
|
|
30
|
+
public readonly held: { type: EntityClass; key: string }[] = [];
|
|
31
|
+
/** The transactions holding locks this one waits for. */
|
|
32
|
+
public waitingFor = new Set<MemoryTransaction>();
|
|
33
|
+
/** The error that aborted it: after a failed statement, as in Postgres, it only rolls back. */
|
|
34
|
+
public aborted: unknown;
|
|
35
|
+
public finished = false;
|
|
36
|
+
public readonly done: Promise<void>;
|
|
37
|
+
private settle!: () => void;
|
|
38
|
+
|
|
39
|
+
public constructor() {
|
|
40
|
+
this.done = new Promise((resolve) => {
|
|
41
|
+
this.settle = resolve;
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
public finish() {
|
|
46
|
+
this.finished = true;
|
|
47
|
+
this.settle();
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* The rows of one data source, held in the process. Reads see what is committed plus their own
|
|
53
|
+
* transaction's writes (read committed); a commit applies a transaction's writes in one step.
|
|
54
|
+
* Rows are copied in and out, so an object held outside can't change what is stored.
|
|
55
|
+
*/
|
|
56
|
+
export class MemoryStore {
|
|
57
|
+
private readonly models: Map<EntityClass, MemoryEntity>;
|
|
58
|
+
private readonly tables = new Map<EntityClass, Map<string, Row>>();
|
|
59
|
+
private readonly sequences = new Map<EntityClass, number>();
|
|
60
|
+
private readonly locks = new Map<
|
|
61
|
+
EntityClass,
|
|
62
|
+
Map<string, Map<MemoryTransaction, LockMode>>
|
|
63
|
+
>();
|
|
64
|
+
|
|
65
|
+
public constructor(entities: readonly MemoryEntity[]) {
|
|
66
|
+
this.models = memoryEntities.check(entities);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
public model(type: EntityClass): MemoryEntity {
|
|
70
|
+
const model = this.models.get(type);
|
|
71
|
+
if (model == null) {
|
|
72
|
+
throw new DataConfigurationError(
|
|
73
|
+
`${type.name} isn't mapped: add mapEntity(${type.name}, …) to memory()'s entities`,
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
return model;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
public begin(): MemoryTransaction {
|
|
80
|
+
return new MemoryTransaction();
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
public commit(tx: MemoryTransaction) {
|
|
84
|
+
this.assertOpen(tx);
|
|
85
|
+
if (tx.aborted !== undefined) {
|
|
86
|
+
this.rollback(tx);
|
|
87
|
+
throw new DataError(
|
|
88
|
+
"The transaction was aborted by an earlier error, so it was rolled back",
|
|
89
|
+
{
|
|
90
|
+
cause: tx.aborted,
|
|
91
|
+
},
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
for (const [type, writes] of tx.writes) {
|
|
95
|
+
const table = this.table(type);
|
|
96
|
+
for (const [key, row] of writes) {
|
|
97
|
+
if (row === null) table.delete(key);
|
|
98
|
+
else table.set(key, row);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
this.end(tx);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
public rollback(tx: MemoryTransaction) {
|
|
105
|
+
this.assertOpen(tx);
|
|
106
|
+
this.end(tx);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
public select(tx: MemoryTransaction, type: EntityClass, query: RowQuery): Promise<Row[]> {
|
|
110
|
+
return this.statement(tx, async () => {
|
|
111
|
+
const model = this.model(type);
|
|
112
|
+
for (const prop of Object.keys(query.where ?? {})) this.assertProp(model, prop);
|
|
113
|
+
for (const prop of Object.keys(query.orderBy ?? {})) this.assertProp(model, prop);
|
|
114
|
+
let found = this.query(tx, type, query);
|
|
115
|
+
if (query.lock === "update") {
|
|
116
|
+
// Lock what matched, then read again: a row another transaction changed while this one
|
|
117
|
+
// waited is read as it now is, and dropped if it no longer matches.
|
|
118
|
+
for (;;) {
|
|
119
|
+
const unlocked = found.filter(([key]) => !this.holds(tx, type, key, "update"));
|
|
120
|
+
if (unlocked.length === 0) break;
|
|
121
|
+
for (const [key] of unlocked) await this.acquire(tx, type, key, "update");
|
|
122
|
+
found = this.query(tx, type, query);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
const props = [...model.fields, ...model.references.map((r) => r.prop)];
|
|
126
|
+
return found.map(([, row]) =>
|
|
127
|
+
Object.fromEntries(props.map((prop) => [prop, copy(row[prop] ?? null)])),
|
|
128
|
+
);
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
public insert(tx: MemoryTransaction, type: EntityClass, rows: Row[]): Promise<Row[]> {
|
|
133
|
+
return this.statement(tx, async () => {
|
|
134
|
+
const model = this.model(type);
|
|
135
|
+
const generated: Row[] = [];
|
|
136
|
+
for (const input of rows) {
|
|
137
|
+
const row = copy(input) as Row;
|
|
138
|
+
const out: Row = {};
|
|
139
|
+
if (model.generated && row[model.generated] == null) {
|
|
140
|
+
const next = (this.sequences.get(type) ?? 0) + 1;
|
|
141
|
+
this.sequences.set(type, next);
|
|
142
|
+
row[model.generated] = next;
|
|
143
|
+
out[model.generated] = next;
|
|
144
|
+
}
|
|
145
|
+
for (const prop of model.key) {
|
|
146
|
+
if (row[prop] == null) throw new DataError(`${model.name}: key ${prop} is empty`);
|
|
147
|
+
}
|
|
148
|
+
await this.checkReferences(
|
|
149
|
+
tx,
|
|
150
|
+
model,
|
|
151
|
+
row,
|
|
152
|
+
model.references.map((r) => r.prop),
|
|
153
|
+
);
|
|
154
|
+
const key = this.keyOf(model, row);
|
|
155
|
+
await this.acquire(tx, type, key, "update");
|
|
156
|
+
if (this.row(tx, type, key)) {
|
|
157
|
+
throw new DataError(`${model.name} ${this.describe(model, row)} already exists`);
|
|
158
|
+
}
|
|
159
|
+
this.write(tx, type, key, row);
|
|
160
|
+
generated.push(out);
|
|
161
|
+
}
|
|
162
|
+
return generated;
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
public update(
|
|
167
|
+
tx: MemoryTransaction,
|
|
168
|
+
type: EntityClass,
|
|
169
|
+
keyRow: Row,
|
|
170
|
+
changes: Row,
|
|
171
|
+
version?: { prop: string; expected: unknown },
|
|
172
|
+
): Promise<number> {
|
|
173
|
+
return this.statement(tx, async () => {
|
|
174
|
+
const model = this.model(type);
|
|
175
|
+
for (const prop of Object.keys(changes)) this.assertProp(model, prop);
|
|
176
|
+
const key = this.keyOf(model, keyRow);
|
|
177
|
+
const changesKey = model.key.some(
|
|
178
|
+
(prop) => prop in changes && !equal(changes[prop], keyRow[prop]),
|
|
179
|
+
);
|
|
180
|
+
await this.acquire(tx, type, key, changesKey ? "update" : "no-key-update");
|
|
181
|
+
const current = this.row(tx, type, key);
|
|
182
|
+
if (current == null) return 0;
|
|
183
|
+
if (version && !equal(current[version.prop], version.expected)) return 0;
|
|
184
|
+
const next = { ...current, ...(copy(changes) as Row) };
|
|
185
|
+
await this.checkReferences(tx, model, next, Object.keys(changes));
|
|
186
|
+
if (!changesKey) {
|
|
187
|
+
this.write(tx, type, key, next);
|
|
188
|
+
return 1;
|
|
189
|
+
}
|
|
190
|
+
const nextKey = this.keyOf(model, next);
|
|
191
|
+
await this.acquire(tx, type, nextKey, "update");
|
|
192
|
+
if (this.row(tx, type, nextKey)) {
|
|
193
|
+
throw new DataError(`${model.name} ${this.describe(model, next)} already exists`);
|
|
194
|
+
}
|
|
195
|
+
this.assertUnreferenced(tx, model, current);
|
|
196
|
+
this.write(tx, type, key, null);
|
|
197
|
+
this.write(tx, type, nextKey, next);
|
|
198
|
+
return 1;
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
public delete(tx: MemoryTransaction, type: EntityClass, keys: Row[]): Promise<void> {
|
|
203
|
+
return this.statement(tx, async () => {
|
|
204
|
+
const model = this.model(type);
|
|
205
|
+
const deleted: { model: MemoryEntity; row: Row }[] = [];
|
|
206
|
+
for (const keyRow of keys) {
|
|
207
|
+
const key = this.keyOf(model, keyRow);
|
|
208
|
+
await this.acquire(tx, type, key, "update");
|
|
209
|
+
const row = this.row(tx, type, key);
|
|
210
|
+
if (row == null) continue;
|
|
211
|
+
this.write(tx, type, key, null);
|
|
212
|
+
deleted.push({ model, row });
|
|
213
|
+
}
|
|
214
|
+
// Then what referenced them: cascaded where the reference says so, refused otherwise.
|
|
215
|
+
for (let i = 0; i < deleted.length; i++) {
|
|
216
|
+
const { model: parent, row } = deleted[i];
|
|
217
|
+
for (const { child, ref, key, row: referencing } of this.referencing(
|
|
218
|
+
tx,
|
|
219
|
+
parent,
|
|
220
|
+
row,
|
|
221
|
+
)) {
|
|
222
|
+
if (ref.onDelete !== "cascade") {
|
|
223
|
+
throw new DataError(
|
|
224
|
+
`Can't delete ${parent.name} ${this.describe(parent, row)}: ${child.name}.${ref.prop} still references it`,
|
|
225
|
+
);
|
|
226
|
+
}
|
|
227
|
+
await this.acquire(tx, child.type, key, "update");
|
|
228
|
+
if (this.row(tx, child.type, key) == null) continue;
|
|
229
|
+
this.write(tx, child.type, key, null);
|
|
230
|
+
deleted.push({ model: child, row: referencing });
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
});
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
// ── Rows ───────────────────────────────────────────────────────────────
|
|
237
|
+
|
|
238
|
+
private query(tx: MemoryTransaction, type: EntityClass, query: RowQuery): [string, Row][] {
|
|
239
|
+
const where = Object.entries(query.where ?? {});
|
|
240
|
+
const found = [...this.rows(tx, type)].filter(([, row]) =>
|
|
241
|
+
where.every(([prop, condition]) => matches(row[prop] ?? null, condition)),
|
|
242
|
+
);
|
|
243
|
+
const orderBy = Object.entries(query.orderBy ?? {});
|
|
244
|
+
if (orderBy.length > 0) {
|
|
245
|
+
found.sort(([, a], [, b]) => {
|
|
246
|
+
for (const [prop, direction] of orderBy) {
|
|
247
|
+
const order = sortOrder(a[prop] ?? null, b[prop] ?? null, direction);
|
|
248
|
+
if (order !== 0) return order;
|
|
249
|
+
}
|
|
250
|
+
return 0;
|
|
251
|
+
});
|
|
252
|
+
}
|
|
253
|
+
return query.limit === undefined ? found : found.slice(0, query.limit);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/** Every row as this transaction sees it: committed, then overlaid with its own writes. */
|
|
257
|
+
private *rows(tx: MemoryTransaction, type: EntityClass): Iterable<[string, Row]> {
|
|
258
|
+
const table = this.table(type);
|
|
259
|
+
const writes = tx.writes.get(type);
|
|
260
|
+
for (const [key, row] of table) {
|
|
261
|
+
const written = writes?.get(key);
|
|
262
|
+
if (written === undefined) yield [key, row];
|
|
263
|
+
else if (written !== null) yield [key, written];
|
|
264
|
+
}
|
|
265
|
+
for (const [key, row] of writes ?? []) {
|
|
266
|
+
if (row !== null && !table.has(key)) yield [key, row];
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
private row(tx: MemoryTransaction, type: EntityClass, key: string): Row | undefined {
|
|
271
|
+
const written = tx.writes.get(type)?.get(key);
|
|
272
|
+
if (written !== undefined) return written ?? undefined;
|
|
273
|
+
return this.table(type).get(key);
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
private write(tx: MemoryTransaction, type: EntityClass, key: string, row: Row | null) {
|
|
277
|
+
let writes = tx.writes.get(type);
|
|
278
|
+
if (writes == null) {
|
|
279
|
+
writes = new Map();
|
|
280
|
+
tx.writes.set(type, writes);
|
|
281
|
+
}
|
|
282
|
+
writes.set(key, row);
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
private table(type: EntityClass): Map<string, Row> {
|
|
286
|
+
let table = this.tables.get(type);
|
|
287
|
+
if (table == null) {
|
|
288
|
+
table = new Map();
|
|
289
|
+
this.tables.set(type, table);
|
|
290
|
+
}
|
|
291
|
+
return table;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** A row's references, as a foreign key checks them: each set one points at a row that exists. */
|
|
295
|
+
private async checkReferences(
|
|
296
|
+
tx: MemoryTransaction,
|
|
297
|
+
model: MemoryEntity,
|
|
298
|
+
row: Row,
|
|
299
|
+
props: string[],
|
|
300
|
+
) {
|
|
301
|
+
for (const ref of model.references) {
|
|
302
|
+
if (!props.includes(ref.prop)) continue;
|
|
303
|
+
const value = row[ref.prop];
|
|
304
|
+
if (value == null) {
|
|
305
|
+
if (ref.nullable) continue;
|
|
306
|
+
throw new DataError(`${model.name}.${ref.prop} can't be empty`);
|
|
307
|
+
}
|
|
308
|
+
const target = this.model(ref.target);
|
|
309
|
+
const key = this.keyOf(target, { [target.key[0]]: value });
|
|
310
|
+
await this.acquire(tx, ref.target, key, "key-share");
|
|
311
|
+
if (this.row(tx, ref.target, key) == null) {
|
|
312
|
+
throw new DataError(
|
|
313
|
+
`${model.name}.${ref.prop} references ${target.name} ${String(value)}, which doesn't exist`,
|
|
314
|
+
);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
private referencing(tx: MemoryTransaction, parent: MemoryEntity, row: Row) {
|
|
320
|
+
const found: {
|
|
321
|
+
child: MemoryEntity;
|
|
322
|
+
ref: MemoryEntity["references"][number];
|
|
323
|
+
key: string;
|
|
324
|
+
row: Row;
|
|
325
|
+
}[] = [];
|
|
326
|
+
if (parent.key.length !== 1) return found;
|
|
327
|
+
const value = row[parent.key[0]];
|
|
328
|
+
for (const child of this.models.values()) {
|
|
329
|
+
for (const ref of child.references) {
|
|
330
|
+
if (ref.target !== parent.type) continue;
|
|
331
|
+
for (const [key, candidate] of this.rows(tx, child.type)) {
|
|
332
|
+
if (equal(candidate[ref.prop], value))
|
|
333
|
+
found.push({ child, ref, key, row: candidate });
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
return found;
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
private assertUnreferenced(tx: MemoryTransaction, model: MemoryEntity, row: Row) {
|
|
341
|
+
const [first] = this.referencing(tx, model, row);
|
|
342
|
+
if (first) {
|
|
343
|
+
throw new DataError(
|
|
344
|
+
`Can't change the key of ${model.name} ${this.describe(model, row)}: ${first.child.name}.${first.ref.prop} references it`,
|
|
345
|
+
);
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
// ── Locks ──────────────────────────────────────────────────────────────
|
|
350
|
+
|
|
351
|
+
/** Take a row lock, waiting while another transaction holds one that conflicts. */
|
|
352
|
+
private async acquire(
|
|
353
|
+
tx: MemoryTransaction,
|
|
354
|
+
type: EntityClass,
|
|
355
|
+
key: string,
|
|
356
|
+
mode: LockMode,
|
|
357
|
+
) {
|
|
358
|
+
let byKey = this.locks.get(type);
|
|
359
|
+
if (byKey == null) {
|
|
360
|
+
byKey = new Map();
|
|
361
|
+
this.locks.set(type, byKey);
|
|
362
|
+
}
|
|
363
|
+
for (;;) {
|
|
364
|
+
let holders = byKey.get(key);
|
|
365
|
+
if (holders == null) {
|
|
366
|
+
holders = new Map();
|
|
367
|
+
byKey.set(key, holders);
|
|
368
|
+
}
|
|
369
|
+
const blocking = [...holders]
|
|
370
|
+
.filter(([other, held]) => other !== tx && CONFLICTS[mode].includes(held))
|
|
371
|
+
.map(([other]) => other);
|
|
372
|
+
if (blocking.length === 0) {
|
|
373
|
+
const mine = holders.get(tx);
|
|
374
|
+
if (mine == null) tx.held.push({ type, key });
|
|
375
|
+
if (mine == null || STRENGTH[mode] > STRENGTH[mine]) holders.set(tx, mode);
|
|
376
|
+
return;
|
|
377
|
+
}
|
|
378
|
+
tx.waitingFor = new Set(blocking);
|
|
379
|
+
if (this.waitsOnItself(tx)) {
|
|
380
|
+
tx.waitingFor = new Set();
|
|
381
|
+
throw new DataError(
|
|
382
|
+
`Deadlock: two transactions each wait for a row the other has locked (${this.model(type).name})`,
|
|
383
|
+
);
|
|
384
|
+
}
|
|
385
|
+
await Promise.race(blocking.map((other) => other.done));
|
|
386
|
+
tx.waitingFor = new Set();
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
private holds(tx: MemoryTransaction, type: EntityClass, key: string, mode: LockMode) {
|
|
391
|
+
const held = this.locks.get(type)?.get(key)?.get(tx);
|
|
392
|
+
return held != null && STRENGTH[held] >= STRENGTH[mode];
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
private waitsOnItself(tx: MemoryTransaction): boolean {
|
|
396
|
+
const seen = new Set<MemoryTransaction>();
|
|
397
|
+
const visit = (other: MemoryTransaction): boolean => {
|
|
398
|
+
if (other === tx) return true;
|
|
399
|
+
if (seen.has(other)) return false;
|
|
400
|
+
seen.add(other);
|
|
401
|
+
return [...other.waitingFor].some(visit);
|
|
402
|
+
};
|
|
403
|
+
return [...tx.waitingFor].some(visit);
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
private end(tx: MemoryTransaction) {
|
|
407
|
+
for (const { type, key } of tx.held) {
|
|
408
|
+
const byKey = this.locks.get(type);
|
|
409
|
+
const holders = byKey?.get(key);
|
|
410
|
+
holders?.delete(tx);
|
|
411
|
+
if (holders?.size === 0) byKey?.delete(key);
|
|
412
|
+
}
|
|
413
|
+
tx.finish();
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
// ── Helpers ────────────────────────────────────────────────────────────
|
|
417
|
+
|
|
418
|
+
/** Run one statement. A failure aborts the transaction, as in Postgres: it can only roll back. */
|
|
419
|
+
private async statement<R>(tx: MemoryTransaction, run: () => Promise<R>): Promise<R> {
|
|
420
|
+
this.assertOpen(tx);
|
|
421
|
+
if (tx.aborted !== undefined) {
|
|
422
|
+
throw new DataError("The transaction was aborted by an earlier error: roll it back", {
|
|
423
|
+
cause: tx.aborted,
|
|
424
|
+
});
|
|
425
|
+
}
|
|
426
|
+
try {
|
|
427
|
+
return await run();
|
|
428
|
+
} catch (err) {
|
|
429
|
+
tx.aborted = err;
|
|
430
|
+
throw err;
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
private assertOpen(tx: MemoryTransaction) {
|
|
435
|
+
if (tx.finished) throw new DataError("The transaction has ended");
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
private assertProp(model: MemoryEntity, prop: string) {
|
|
439
|
+
if (!model.fields.includes(prop) && !model.references.some((r) => r.prop === prop)) {
|
|
440
|
+
throw new DataConfigurationError(`${model.name} has no field "${prop}"`);
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
/** A row's key as one string. Dates count by their instant. */
|
|
445
|
+
private keyOf(model: MemoryEntity, row: Row): string {
|
|
446
|
+
return JSON.stringify(
|
|
447
|
+
model.key.map((prop) => {
|
|
448
|
+
const value = row[prop];
|
|
449
|
+
return value instanceof Date ? { date: value.getTime() } : value;
|
|
450
|
+
}),
|
|
451
|
+
);
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
private describe(model: MemoryEntity, row: Row): string {
|
|
455
|
+
return model.key.map((prop) => String(row[prop])).join(", ");
|
|
456
|
+
}
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/** Whether a stored value meets a condition, with SQL's nulls: only `null` and `ne` match an empty value. */
|
|
460
|
+
function matches(value: unknown, condition: Comparison<unknown>): boolean {
|
|
461
|
+
if (condition === null) return value === null;
|
|
462
|
+
const operator = comparison.operatorOf(condition);
|
|
463
|
+
if (!operator) return value !== null && equal(value, condition);
|
|
464
|
+
const [op, operand] = operator;
|
|
465
|
+
if (op === "ne" && operand === null) return value !== null;
|
|
466
|
+
if (value === null) return false;
|
|
467
|
+
if (op === "in") return (operand as unknown[]).some((v) => equal(value, v));
|
|
468
|
+
if (op === "ne") return !equal(value, operand);
|
|
469
|
+
if (operand === null) return false;
|
|
470
|
+
const order = compare(value, operand);
|
|
471
|
+
if (op === "gt") return order > 0;
|
|
472
|
+
if (op === "gte") return order >= 0;
|
|
473
|
+
if (op === "lt") return order < 0;
|
|
474
|
+
return order <= 0;
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
/** Postgres's order: empty values last ascending, first descending. */
|
|
478
|
+
function sortOrder(a: unknown, b: unknown, direction: "asc" | "desc"): number {
|
|
479
|
+
const sign = direction === "desc" ? -1 : 1;
|
|
480
|
+
if (a === null || b === null) {
|
|
481
|
+
if (a === b) return 0;
|
|
482
|
+
return (a === null ? 1 : -1) * sign;
|
|
483
|
+
}
|
|
484
|
+
return compare(a, b) * sign;
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
function compare(a: unknown, b: unknown): number {
|
|
488
|
+
const x = a instanceof Date ? a.getTime() : a;
|
|
489
|
+
const y = b instanceof Date ? b.getTime() : b;
|
|
490
|
+
const kind = typeof x;
|
|
491
|
+
if (kind !== typeof y || !["number", "string", "bigint", "boolean"].includes(kind)) {
|
|
492
|
+
throw new DataError(`Can't compare ${String(a)} with ${String(b)}`);
|
|
493
|
+
}
|
|
494
|
+
if ((x as number) < (y as number)) return -1;
|
|
495
|
+
return (x as number) > (y as number) ? 1 : 0;
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
function equal(a: unknown, b: unknown): boolean {
|
|
499
|
+
if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
|
|
500
|
+
if (a !== null && b !== null && typeof a === "object" && typeof b === "object") {
|
|
501
|
+
return JSON.stringify(a) === JSON.stringify(b);
|
|
502
|
+
}
|
|
503
|
+
return a === b;
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
function copy(value: unknown): unknown {
|
|
507
|
+
return value !== null && typeof value === "object" ? structuredClone(value) : value;
|
|
508
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
// An app on the memory provider, as a developer composes it: repositories over the unit of work,
|
|
2
|
+
// with no database and no database config.
|
|
3
|
+
import "reflect-metadata";
|
|
4
|
+
import { Builder } from "@decohere/core/hosting";
|
|
5
|
+
import { ServiceContainerBuilder } from "@decohere/crucible";
|
|
6
|
+
import { injectable } from "@decohere/crucible/decorators";
|
|
7
|
+
import {
|
|
8
|
+
DataConfigurationError,
|
|
9
|
+
DEFAULT_DATA_SOURCE,
|
|
10
|
+
type IUnitOfWork,
|
|
11
|
+
injectUnitOfWork,
|
|
12
|
+
Repository,
|
|
13
|
+
} from "@decohere/data";
|
|
14
|
+
import { describe, expect, it } from "vitest";
|
|
15
|
+
import { mapEntity, memory, type MemoryModuleConfig } from "../src/index.js";
|
|
16
|
+
import { Book, book, entities, Shelf, shelf } from "./model.js";
|
|
17
|
+
|
|
18
|
+
@injectable()
|
|
19
|
+
class ShelfRepository extends Repository<Shelf> {
|
|
20
|
+
public constructor(@injectUnitOfWork() unitOfWork: IUnitOfWork) {
|
|
21
|
+
super(unitOfWork, Shelf);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function build(config: Partial<MemoryModuleConfig> = {}) {
|
|
26
|
+
return Builder.create(new ServiceContainerBuilder())
|
|
27
|
+
.use(memory({ entities, repositories: [ShelfRepository], ...config }))
|
|
28
|
+
.build();
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
async function start(config: Partial<MemoryModuleConfig> = {}) {
|
|
32
|
+
const app = await build(config);
|
|
33
|
+
await app.start({ port: 0, shutdownSignals: false, startRetry: false });
|
|
34
|
+
return app;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
describe("memory()", () => {
|
|
38
|
+
it("gives each request a unit of work, and what one request commits the next one reads", async () => {
|
|
39
|
+
await using app = await start();
|
|
40
|
+
{
|
|
41
|
+
await using scope = app.services.beginScope("a request");
|
|
42
|
+
const shelves = scope.resolve(ShelfRepository);
|
|
43
|
+
const s = shelf("s1", "fiction");
|
|
44
|
+
s.books.add(book("b1", "Dune", s));
|
|
45
|
+
shelves.add(s);
|
|
46
|
+
await scope.resolve<IUnitOfWork>(DEFAULT_DATA_SOURCE).commit();
|
|
47
|
+
}
|
|
48
|
+
await using scope = app.services.beginScope("a later request");
|
|
49
|
+
const found = await scope.resolve(ShelfRepository).findById("s1", ["books"]);
|
|
50
|
+
expect([...found.books].map((b) => b.title)).toEqual(["Dune"]);
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
it("gives each app its own rows", async () => {
|
|
54
|
+
await using first = await start();
|
|
55
|
+
await using second = await start();
|
|
56
|
+
{
|
|
57
|
+
await using scope = first.services.beginScope("a request");
|
|
58
|
+
const uow = scope.resolve<IUnitOfWork>(DEFAULT_DATA_SOURCE);
|
|
59
|
+
uow.add(shelf("s1", "fiction"));
|
|
60
|
+
await uow.commit();
|
|
61
|
+
}
|
|
62
|
+
await using scope = second.services.beginScope("a request");
|
|
63
|
+
expect(await scope.resolve(ShelfRepository).find()).toEqual([]);
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
it("seeds when the app starts, not when it is built", async () => {
|
|
67
|
+
const seed = async (uow: IUnitOfWork) => uow.add(shelf("s1", "seeded"));
|
|
68
|
+
await using app = await build({ seed });
|
|
69
|
+
const read = async () => {
|
|
70
|
+
await using scope = app.services.beginScope("a request");
|
|
71
|
+
return scope.resolve(ShelfRepository).find();
|
|
72
|
+
};
|
|
73
|
+
expect(await read()).toEqual([]);
|
|
74
|
+
await app.start({ port: 0, shutdownSignals: false, startRetry: false });
|
|
75
|
+
expect((await read()).map((s) => s.label)).toEqual(["seeded"]);
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
it("fails the build when a mapping points at a class that isn't mapped", async () => {
|
|
79
|
+
await expect(build({ entities: [entities[0]] })).rejects.toThrow(
|
|
80
|
+
"Shelf.books points at Book, which isn't mapped: add it to entities",
|
|
81
|
+
);
|
|
82
|
+
await expect(
|
|
83
|
+
build({
|
|
84
|
+
entities: [
|
|
85
|
+
entities[0],
|
|
86
|
+
mapEntity(Book, {
|
|
87
|
+
fields: ["title"],
|
|
88
|
+
references: [{ prop: "shelf", target: Book }],
|
|
89
|
+
}),
|
|
90
|
+
],
|
|
91
|
+
}),
|
|
92
|
+
).rejects.toThrow("Shelf.books: Book.shelf must be a reference to Shelf");
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
it("needs a name for each data source when there are several", () => {
|
|
96
|
+
expect(() => memory([{ entities }, { name: "audit", entities }])).toThrow(
|
|
97
|
+
DataConfigurationError,
|
|
98
|
+
);
|
|
99
|
+
});
|
|
100
|
+
});
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
// What the memory store does that the shared contract cases can't show: the database's own rules
|
|
2
|
+
// (foreign keys, row locks, deadlocks, SQL's nulls) and rows copied in and out.
|
|
3
|
+
import { OptimisticLockError, TrackingUnitOfWork } from "@decohere/data";
|
|
4
|
+
import { describe, expect, it } from "vitest";
|
|
5
|
+
import { MemoryRowStore, MemoryStore } from "../src/index.js";
|
|
6
|
+
import { Book, book, entities, Shelf, shelf } from "./model.js";
|
|
7
|
+
|
|
8
|
+
function open() {
|
|
9
|
+
const store = new MemoryStore(entities);
|
|
10
|
+
return () => new TrackingUnitOfWork(new MemoryRowStore(store));
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
async function seeded() {
|
|
14
|
+
const begin = open();
|
|
15
|
+
await using uow = begin();
|
|
16
|
+
const s = shelf("s1", "fiction");
|
|
17
|
+
s.books.add(book("b1", "Dune", s, { rating: 5, meta: { tags: ["sand"] } }));
|
|
18
|
+
s.books.add(book("b2", "Emma", s));
|
|
19
|
+
uow.add(s);
|
|
20
|
+
await uow.commit();
|
|
21
|
+
return begin;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Settles every pending promise callback, so a waiting unit of work shows it is still waiting. */
|
|
25
|
+
const settle = () => new Promise((resolve) => setImmediate(resolve));
|
|
26
|
+
|
|
27
|
+
describe("memory store", () => {
|
|
28
|
+
it("refuses to delete a row another row still references, and keeps both", async () => {
|
|
29
|
+
const begin = await seeded();
|
|
30
|
+
{
|
|
31
|
+
await using uow = begin();
|
|
32
|
+
uow.remove(await uow.findById(Shelf, "s1"));
|
|
33
|
+
await expect(uow.commit()).rejects.toThrow(
|
|
34
|
+
"Can't delete Shelf s1: Book.shelf still references it",
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
await using uow = begin();
|
|
38
|
+
expect(await uow.findById(Shelf, "s1", ["books"])).toMatchObject({ label: "fiction" });
|
|
39
|
+
expect(await uow.find(Book)).toHaveLength(2);
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
it("refuses a reference to a row that doesn't exist, or none where one is required", async () => {
|
|
43
|
+
// The unit of work inserts what an entity references, so this goes to the rows directly.
|
|
44
|
+
const rows = new MemoryRowStore(new MemoryStore(entities));
|
|
45
|
+
await expect(
|
|
46
|
+
rows.insert(Book, [{ id: "b9", title: "Lost", shelf: "nowhere" }]),
|
|
47
|
+
).rejects.toThrow("Book.shelf references Shelf nowhere, which doesn't exist");
|
|
48
|
+
await expect(
|
|
49
|
+
rows.insert(Book, [{ id: "b9", title: "Lost", shelf: null }]),
|
|
50
|
+
).rejects.toThrow("Book.shelf can't be empty");
|
|
51
|
+
expect(await rows.select(Book, {})).toEqual([]);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
it("refuses a second row with the same key", async () => {
|
|
55
|
+
const begin = await seeded();
|
|
56
|
+
await using uow = begin();
|
|
57
|
+
uow.add(shelf("s1", "again"));
|
|
58
|
+
await expect(uow.commit()).rejects.toThrow("Shelf s1 already exists");
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it("stores copies: changing an object after commit, or a loaded one without commit, changes nothing stored", async () => {
|
|
62
|
+
const begin = open();
|
|
63
|
+
const s = shelf("s1", "fiction");
|
|
64
|
+
const meta = { tags: ["sand"] };
|
|
65
|
+
const published = new Date("1965-08-01T00:00:00Z");
|
|
66
|
+
{
|
|
67
|
+
await using uow = begin();
|
|
68
|
+
uow.add(s);
|
|
69
|
+
uow.add(book("b1", "Dune", s, { meta, published }));
|
|
70
|
+
await uow.commit();
|
|
71
|
+
}
|
|
72
|
+
meta.tags.push("worms");
|
|
73
|
+
published.setUTCFullYear(2000);
|
|
74
|
+
{
|
|
75
|
+
await using uow = begin();
|
|
76
|
+
const loaded = await uow.findById(Book, "b1");
|
|
77
|
+
loaded.meta.tags.push("spice");
|
|
78
|
+
}
|
|
79
|
+
await using uow = begin();
|
|
80
|
+
const stored = await uow.findById(Book, "b1");
|
|
81
|
+
expect(stored.meta).toEqual({ tags: ["sand"] });
|
|
82
|
+
expect(stored.published).toEqual(new Date("1965-08-01T00:00:00Z"));
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
it("compares and orders empty values as SQL does", async () => {
|
|
86
|
+
const begin = await seeded();
|
|
87
|
+
await using uow = begin();
|
|
88
|
+
expect((await uow.find(Book, { where: { rating: { ne: 4 } } })).map((b) => b.id)).toEqual([
|
|
89
|
+
"b1",
|
|
90
|
+
]);
|
|
91
|
+
expect((await uow.find(Book, { where: { rating: { lt: 9 } } })).map((b) => b.id)).toEqual([
|
|
92
|
+
"b1",
|
|
93
|
+
]);
|
|
94
|
+
const asc = await uow.find(Book, { orderBy: { rating: "asc" } });
|
|
95
|
+
expect(asc.map((b) => b.id)).toEqual(["b1", "b2"]);
|
|
96
|
+
const desc = await uow.find(Book, { orderBy: { rating: "desc" } });
|
|
97
|
+
expect(desc.map((b) => b.id)).toEqual(["b2", "b1"]);
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
it('serialises lock: "update" on a row: the second waits for the first to commit, then reads its write', async () => {
|
|
101
|
+
const begin = await seeded();
|
|
102
|
+
await using first = begin();
|
|
103
|
+
await using second = begin();
|
|
104
|
+
const [mine] = await first.find(Shelf, { where: { id: "s1" }, lock: "update" });
|
|
105
|
+
let theirs: Shelf | undefined;
|
|
106
|
+
const waiting = second
|
|
107
|
+
.find(Shelf, { where: { id: "s1" }, lock: "update" })
|
|
108
|
+
.then(([found]) => (theirs = found));
|
|
109
|
+
await settle();
|
|
110
|
+
expect(theirs).toBeUndefined();
|
|
111
|
+
mine.label = "classics";
|
|
112
|
+
await first.commit();
|
|
113
|
+
await waiting;
|
|
114
|
+
expect(theirs).toMatchObject({ label: "classics", version: 2 });
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
it("makes two commits updating one row at once take turns: the later one loses on its version", async () => {
|
|
118
|
+
const begin = await seeded();
|
|
119
|
+
await using first = begin();
|
|
120
|
+
await using second = begin();
|
|
121
|
+
(await first.findById(Shelf, "s1")).label = "first";
|
|
122
|
+
(await second.findById(Shelf, "s1")).label = "second";
|
|
123
|
+
const [a, b] = await Promise.allSettled([first.commit(), second.commit()]);
|
|
124
|
+
expect(a.status).toBe("fulfilled");
|
|
125
|
+
expect(b).toMatchObject({ status: "rejected", reason: expect.any(OptimisticLockError) });
|
|
126
|
+
await using check = begin();
|
|
127
|
+
expect(await check.findById(Shelf, "s1")).toMatchObject({ label: "first", version: 2 });
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
it("ends a deadlock by failing the unit of work that would wait for itself", async () => {
|
|
131
|
+
const begin = await seeded();
|
|
132
|
+
{
|
|
133
|
+
await using uow = begin();
|
|
134
|
+
uow.add(shelf("s2", "poetry"));
|
|
135
|
+
await uow.commit();
|
|
136
|
+
}
|
|
137
|
+
await using first = begin();
|
|
138
|
+
await using second = begin();
|
|
139
|
+
await first.find(Shelf, { where: { id: "s1" }, lock: "update" });
|
|
140
|
+
await second.find(Shelf, { where: { id: "s2" }, lock: "update" });
|
|
141
|
+
const firstWaits = first.find(Shelf, { where: { id: "s2" }, lock: "update" });
|
|
142
|
+
await settle();
|
|
143
|
+
await expect(second.find(Shelf, { where: { id: "s1" }, lock: "update" })).rejects.toThrow(
|
|
144
|
+
/Deadlock/,
|
|
145
|
+
);
|
|
146
|
+
await second[Symbol.asyncDispose]();
|
|
147
|
+
await expect(firstWaits).resolves.toHaveLength(1);
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
it("rejects a query on a property that isn't mapped", async () => {
|
|
151
|
+
const begin = await seeded();
|
|
152
|
+
await using uow = begin();
|
|
153
|
+
await expect(uow.find(Book, { where: { nope: 1 } as never })).rejects.toThrow(
|
|
154
|
+
'Book has no field "nope"',
|
|
155
|
+
);
|
|
156
|
+
});
|
|
157
|
+
});
|
package/tests/model.ts
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// A small domain for the memory provider's own tests: a shelf of books, each with notes.
|
|
2
|
+
import { type Children, ChildList } from "@decohere/data";
|
|
3
|
+
import { mapEntity } from "../src/index.js";
|
|
4
|
+
|
|
5
|
+
export class Shelf {
|
|
6
|
+
public id!: string;
|
|
7
|
+
public label!: string;
|
|
8
|
+
public version!: number;
|
|
9
|
+
public books: Children<Book> = new ChildList();
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export class Book {
|
|
13
|
+
public id!: string;
|
|
14
|
+
public title!: string;
|
|
15
|
+
public shelf!: Shelf;
|
|
16
|
+
public rating: number | null = null;
|
|
17
|
+
public published: Date | null = null;
|
|
18
|
+
public meta: { tags: string[] } | null = null;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export function shelf(id: string, label: string) {
|
|
22
|
+
return Object.assign(new Shelf(), { id, label });
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export function book(id: string, title: string, s: Shelf, more: Partial<Book> = {}) {
|
|
26
|
+
return Object.assign(new Book(), { id, title, shelf: s, ...more });
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export const entities = [
|
|
30
|
+
mapEntity(Shelf, {
|
|
31
|
+
fields: ["label"],
|
|
32
|
+
version: "version",
|
|
33
|
+
children: [{ prop: "books", target: Book, parentRef: "shelf" }],
|
|
34
|
+
}),
|
|
35
|
+
mapEntity(Book, {
|
|
36
|
+
fields: ["title", "rating", "published", "meta"],
|
|
37
|
+
references: [{ prop: "shelf", target: Shelf }],
|
|
38
|
+
}),
|
|
39
|
+
];
|