@sdflc/backend-helpers 1.0.112 → 1.0.114
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 +1422 -146
- package/build/BaseController.d.ts +20 -0
- package/build/BaseController.js +64 -0
- package/build/BaseCore.d.ts +586 -33
- package/build/BaseCore.js +821 -127
- package/build/BaseExternalApiGateway.d.ts +16 -0
- package/build/BaseExternalApiGateway.js +54 -0
- package/build/BaseGateway.d.ts +455 -17
- package/build/BaseGateway.js +502 -56
- package/build/BaseRestApiCrudController.d.ts +37 -0
- package/build/BaseRestApiCrudController.js +134 -0
- package/build/DataCache.d.ts +116 -5
- package/build/DataCache.js +144 -22
- package/build/Database.d.ts +165 -4
- package/build/Database.js +224 -51
- package/build/DbMigratorAndSeeder.d.ts +127 -26
- package/build/DbMigratorAndSeeder.js +180 -69
- package/build/IpRateLimiter.d.ts +105 -0
- package/build/IpRateLimiter.js +104 -0
- package/build/RedisDataLoader.d.ts +144 -21
- package/build/RedisDataLoader.js +178 -49
- package/build/apiContext.d.ts +0 -8
- package/build/apiContext.js +30 -32
- package/build/checkItHelpers.d.ts +32 -0
- package/build/checkItHelpers.js +73 -7
- package/build/commonValidators.d.ts +107 -16
- package/build/commonValidators.js +211 -106
- package/build/configBuilder.d.ts +23 -0
- package/build/configBuilder.js +73 -0
- package/build/constants.d.ts +134 -17
- package/build/constants.js +95 -15
- package/build/dbHelpers.d.ts +89 -29
- package/build/dbHelpers.js +175 -86
- package/build/dbSeeder.d.ts +10 -1
- package/build/dbSeeder.js +80 -15
- package/build/dbTableHelpers.d.ts +122 -5
- package/build/dbTableHelpers.js +151 -13
- package/build/downloadHelpers.d.ts +24 -1
- package/build/downloadHelpers.js +51 -21
- package/build/esm/BaseController.d.ts +20 -0
- package/build/esm/BaseController.js +58 -0
- package/build/esm/BaseCore.d.ts +586 -33
- package/build/esm/BaseCore.js +812 -118
- package/build/esm/BaseExternalApiGateway.d.ts +16 -0
- package/build/esm/BaseExternalApiGateway.js +48 -0
- package/build/esm/BaseGateway.d.ts +455 -17
- package/build/esm/BaseGateway.js +503 -57
- package/build/esm/BaseRestApiCrudController.d.ts +37 -0
- package/build/esm/BaseRestApiCrudController.js +131 -0
- package/build/esm/DataCache.d.ts +116 -5
- package/build/esm/DataCache.js +142 -20
- package/build/esm/Database.d.ts +165 -4
- package/build/esm/Database.js +224 -51
- package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
- package/build/esm/DbMigratorAndSeeder.js +184 -71
- package/build/esm/IpRateLimiter.d.ts +105 -0
- package/build/esm/IpRateLimiter.js +100 -0
- package/build/esm/RedisDataLoader.d.ts +144 -21
- package/build/esm/RedisDataLoader.js +179 -50
- package/build/esm/apiContext.d.ts +0 -8
- package/build/esm/apiContext.js +30 -32
- package/build/esm/checkItHelpers.d.ts +32 -0
- package/build/esm/checkItHelpers.js +73 -7
- package/build/esm/commonValidators.d.ts +107 -16
- package/build/esm/commonValidators.js +209 -105
- package/build/esm/configBuilder.d.ts +23 -0
- package/build/esm/configBuilder.js +69 -0
- package/build/esm/constants.d.ts +134 -17
- package/build/esm/constants.js +94 -14
- package/build/esm/dbHelpers.d.ts +89 -29
- package/build/esm/dbHelpers.js +171 -81
- package/build/esm/dbSeeder.d.ts +10 -1
- package/build/esm/dbSeeder.js +81 -16
- package/build/esm/dbTableHelpers.d.ts +122 -5
- package/build/esm/dbTableHelpers.js +152 -14
- package/build/esm/downloadHelpers.d.ts +24 -1
- package/build/esm/downloadHelpers.js +51 -21
- package/build/esm/index.d.ts +6 -2
- package/build/esm/index.js +6 -2
- package/build/esm/interfaces/ApiContext.d.ts +33 -3
- package/build/esm/interfaces/ApiContext.js +1 -0
- package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/esm/interfaces/BaseCorePropsInterface.d.ts +146 -9
- package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
- package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/esm/interfaces/BuildConfigOptions.js +1 -0
- package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/esm/interfaces/CacheInterface.d.ts +18 -1
- package/build/esm/interfaces/CacheInterface.js +1 -0
- package/build/esm/interfaces/CoreActionInterface.d.ts +60 -0
- package/build/esm/interfaces/CoreActionInterface.js +1 -0
- package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
- package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/esm/interfaces/DatabaseOptions.js +1 -0
- package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
- package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/esm/interfaces/ListArgsInterface.js +1 -0
- package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
- package/build/esm/interfaces/LoaderInterface.js +1 -0
- package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
- package/build/esm/interfaces/UserTokenParams.js +1 -0
- package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/esm/interfaces/index.d.ts +4 -0
- package/build/esm/interfaces/index.js +4 -0
- package/build/esm/knexConfigBuilder.d.ts +25 -0
- package/build/esm/knexConfigBuilder.js +100 -36
- package/build/esm/parseIds.d.ts +6 -0
- package/build/esm/parseIds.js +13 -0
- package/build/esm/passwordHelpers.d.ts +22 -0
- package/build/esm/passwordHelpers.js +40 -8
- package/build/esm/redisClient.d.ts +57 -4
- package/build/esm/redisClient.js +40 -54
- package/build/esm/resolveClientIp.d.ts +15 -0
- package/build/esm/resolveClientIp.js +34 -0
- package/build/esm/resolversHelpers.d.ts +21 -1
- package/build/esm/resolversHelpers.js +48 -26
- package/build/esm/userToken.d.ts +50 -1
- package/build/esm/userToken.js +85 -20
- package/build/esm/utils.d.ts +20 -2
- package/build/esm/utils.js +23 -13
- package/build/index.d.ts +6 -2
- package/build/index.js +6 -2
- package/build/interfaces/ApiContext.d.ts +33 -3
- package/build/interfaces/ApiContext.js +1 -0
- package/build/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/interfaces/BaseControllerPropsInterface.js +2 -0
- package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/interfaces/BaseCorePropsInterface.d.ts +146 -9
- package/build/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
- package/build/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/interfaces/BuildConfigOptions.js +1 -0
- package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/interfaces/CacheInterface.d.ts +18 -1
- package/build/interfaces/CacheInterface.js +1 -0
- package/build/interfaces/CoreActionInterface.d.ts +60 -0
- package/build/interfaces/CoreActionInterface.js +1 -0
- package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/interfaces/DataCachePropsInterface.js +3 -0
- package/build/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/interfaces/DatabaseOptions.js +1 -0
- package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/interfaces/DatabaseReadInterface.js +1 -0
- package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/interfaces/ListArgsInterface.js +1 -0
- package/build/interfaces/LoaderInterface.d.ts +36 -1
- package/build/interfaces/LoaderInterface.js +1 -0
- package/build/interfaces/UserTokenParams.d.ts +23 -5
- package/build/interfaces/UserTokenParams.js +1 -0
- package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/interfaces/index.d.ts +4 -0
- package/build/interfaces/index.js +4 -0
- package/build/knexConfigBuilder.d.ts +25 -0
- package/build/knexConfigBuilder.js +99 -35
- package/build/parseIds.d.ts +6 -0
- package/build/parseIds.js +17 -0
- package/build/passwordHelpers.d.ts +22 -0
- package/build/passwordHelpers.js +40 -8
- package/build/redisClient.d.ts +57 -4
- package/build/redisClient.js +40 -54
- package/build/resolveClientIp.d.ts +15 -0
- package/build/resolveClientIp.js +38 -0
- package/build/resolversHelpers.d.ts +21 -1
- package/build/resolversHelpers.js +48 -26
- package/build/userToken.d.ts +50 -1
- package/build/userToken.js +85 -20
- package/build/utils.d.ts +20 -2
- package/build/utils.js +24 -16
- package/package.json +19 -18
- package/build/baseController.d.ts +0 -17
- package/build/baseController.js +0 -64
- package/build/configBulder.d.ts +0 -2
- package/build/configBulder.js +0 -36
- package/build/esm/baseController.d.ts +0 -17
- package/build/esm/baseController.js +0 -58
- package/build/esm/configBulder.d.ts +0 -2
- package/build/esm/configBulder.js +0 -32
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { BaseController } from './BaseController';
|
|
2
|
+
import { BaseRestApiCrudControllerPropsInterface } from './interfaces';
|
|
3
|
+
declare class BaseRestApiCrudController extends BaseController {
|
|
4
|
+
protected coreToUse: string;
|
|
5
|
+
protected getContext: (req: any) => Promise<any> | any;
|
|
6
|
+
protected disableList: boolean;
|
|
7
|
+
protected disableGet: boolean;
|
|
8
|
+
protected disableGetMany: boolean;
|
|
9
|
+
protected disableCreate: boolean;
|
|
10
|
+
protected disableCreateMany: boolean;
|
|
11
|
+
protected disableUpdate: boolean;
|
|
12
|
+
protected disableUpdateMany: boolean;
|
|
13
|
+
protected disableRemove: boolean;
|
|
14
|
+
protected disableRemoveMany: boolean;
|
|
15
|
+
constructor(props: BaseRestApiCrudControllerPropsInterface);
|
|
16
|
+
protected resolveCore(req: any): Promise<any>;
|
|
17
|
+
init(props: {
|
|
18
|
+
app: any;
|
|
19
|
+
root: string;
|
|
20
|
+
}): void;
|
|
21
|
+
protected list(req: any): Promise<any>;
|
|
22
|
+
/**
|
|
23
|
+
* Handles GET /:id — routes to core.get() for a single id,
|
|
24
|
+
* or core.getMany() when the :id param contains commas.
|
|
25
|
+
*/
|
|
26
|
+
protected getOrGetMany(req: any): Promise<any>;
|
|
27
|
+
protected create(req: any): Promise<any>;
|
|
28
|
+
protected createMany(req: any): Promise<any>;
|
|
29
|
+
protected update(req: any): Promise<any>;
|
|
30
|
+
protected updateMany(req: any): Promise<any>;
|
|
31
|
+
/**
|
|
32
|
+
* Handles DELETE /:id — routes to core.remove() for a single id,
|
|
33
|
+
* or core.removeMany() when the :id param contains commas.
|
|
34
|
+
*/
|
|
35
|
+
protected removeOrRemoveMany(req: any): Promise<any>;
|
|
36
|
+
}
|
|
37
|
+
export { BaseRestApiCrudController };
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
// ./src/baseRestApiCrudController.ts
|
|
2
|
+
import { BaseController } from './BaseController';
|
|
3
|
+
import { parseIds } from './parseIds';
|
|
4
|
+
class BaseRestApiCrudController extends BaseController {
|
|
5
|
+
coreToUse;
|
|
6
|
+
getContext;
|
|
7
|
+
disableList;
|
|
8
|
+
disableGet;
|
|
9
|
+
disableGetMany;
|
|
10
|
+
disableCreate;
|
|
11
|
+
disableCreateMany;
|
|
12
|
+
disableUpdate;
|
|
13
|
+
disableUpdateMany;
|
|
14
|
+
disableRemove;
|
|
15
|
+
disableRemoveMany;
|
|
16
|
+
constructor(props) {
|
|
17
|
+
super(props);
|
|
18
|
+
const { prefix, core, getContext } = props || {};
|
|
19
|
+
if (!getContext) {
|
|
20
|
+
throw new Error('BaseRestApiCrudController: `getContext` is required');
|
|
21
|
+
}
|
|
22
|
+
this.coreToUse = core || `${prefix}Core`;
|
|
23
|
+
this.getContext = getContext;
|
|
24
|
+
this.disableList = props.disableList ?? false;
|
|
25
|
+
this.disableGet = props.disableGet ?? false;
|
|
26
|
+
this.disableGetMany = props.disableGetMany ?? false;
|
|
27
|
+
this.disableCreate = props.disableCreate ?? false;
|
|
28
|
+
this.disableCreateMany = props.disableCreateMany ?? false;
|
|
29
|
+
this.disableUpdate = props.disableUpdate ?? false;
|
|
30
|
+
this.disableUpdateMany = props.disableUpdateMany ?? false;
|
|
31
|
+
this.disableRemove = props.disableRemove ?? false;
|
|
32
|
+
this.disableRemoveMany = props.disableRemoveMany ?? false;
|
|
33
|
+
}
|
|
34
|
+
async resolveCore(req) {
|
|
35
|
+
const context = await this.getContext(req);
|
|
36
|
+
const core = context?.cores?.[this.coreToUse];
|
|
37
|
+
if (!core) {
|
|
38
|
+
throw new Error(`BaseRestApiCrudController: core "${this.coreToUse}" not found in context`);
|
|
39
|
+
}
|
|
40
|
+
return core;
|
|
41
|
+
}
|
|
42
|
+
init(props) {
|
|
43
|
+
const { app, root } = props || {};
|
|
44
|
+
if (!app || !root) {
|
|
45
|
+
throw new Error('BaseRestApiCrudController.init: `app` and `root` are required');
|
|
46
|
+
}
|
|
47
|
+
if (!this.disableList) {
|
|
48
|
+
app.get(root, this.json(this.list.bind(this)));
|
|
49
|
+
}
|
|
50
|
+
// GET /:id — branches to get() or getMany() based on comma presence
|
|
51
|
+
if (!this.disableGet || !this.disableGetMany) {
|
|
52
|
+
app.get(`${root}/:id`, this.json(this.getOrGetMany.bind(this)));
|
|
53
|
+
}
|
|
54
|
+
if (!this.disableCreate) {
|
|
55
|
+
app.post(root, this.json(this.create.bind(this)));
|
|
56
|
+
}
|
|
57
|
+
if (!this.disableCreateMany) {
|
|
58
|
+
app.post(`${root}/many`, this.json(this.createMany.bind(this)));
|
|
59
|
+
}
|
|
60
|
+
if (!this.disableUpdate) {
|
|
61
|
+
app.put(`${root}/:id`, this.json(this.update.bind(this)));
|
|
62
|
+
}
|
|
63
|
+
if (!this.disableUpdateMany) {
|
|
64
|
+
app.put(`${root}/many`, this.json(this.updateMany.bind(this)));
|
|
65
|
+
}
|
|
66
|
+
// DELETE /:id — branches to remove() or removeMany() based on comma presence
|
|
67
|
+
if (!this.disableRemove || !this.disableRemoveMany) {
|
|
68
|
+
app.delete(`${root}/:id`, this.json(this.removeOrRemoveMany.bind(this)));
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
// ─── Route handlers ────────────────────────────────────────────────────────
|
|
72
|
+
async list(req) {
|
|
73
|
+
const core = await this.resolveCore(req);
|
|
74
|
+
return core.list({ params: req.query });
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Handles GET /:id — routes to core.get() for a single id,
|
|
78
|
+
* or core.getMany() when the :id param contains commas.
|
|
79
|
+
*/
|
|
80
|
+
async getOrGetMany(req) {
|
|
81
|
+
const core = await this.resolveCore(req);
|
|
82
|
+
const [isSingle, ids] = parseIds(req.params.id);
|
|
83
|
+
if (isSingle) {
|
|
84
|
+
if (this.disableGet) {
|
|
85
|
+
throw new Error(`GET by single id is disabled on this resource`);
|
|
86
|
+
}
|
|
87
|
+
return core.get({ params: { ...req.query, id: ids[0] } });
|
|
88
|
+
}
|
|
89
|
+
if (this.disableGetMany) {
|
|
90
|
+
throw new Error(`GET by multiple ids is disabled on this resource`);
|
|
91
|
+
}
|
|
92
|
+
return core.getMany({ params: { ...req.query, ids } });
|
|
93
|
+
}
|
|
94
|
+
async create(req) {
|
|
95
|
+
const core = await this.resolveCore(req);
|
|
96
|
+
return core.create({ params: req.body });
|
|
97
|
+
}
|
|
98
|
+
async createMany(req) {
|
|
99
|
+
const core = await this.resolveCore(req);
|
|
100
|
+
const items = Array.isArray(req.body) ? req.body : [req.body];
|
|
101
|
+
return core.createMany({ params: items });
|
|
102
|
+
}
|
|
103
|
+
async update(req) {
|
|
104
|
+
const core = await this.resolveCore(req);
|
|
105
|
+
return core.update({ params: { ...req.body, id: req.params.id } });
|
|
106
|
+
}
|
|
107
|
+
async updateMany(req) {
|
|
108
|
+
const core = await this.resolveCore(req);
|
|
109
|
+
const items = Array.isArray(req.body) ? req.body : [req.body];
|
|
110
|
+
return core.updateMany({ params: items });
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Handles DELETE /:id — routes to core.remove() for a single id,
|
|
114
|
+
* or core.removeMany() when the :id param contains commas.
|
|
115
|
+
*/
|
|
116
|
+
async removeOrRemoveMany(req) {
|
|
117
|
+
const core = await this.resolveCore(req);
|
|
118
|
+
const [isSingle, ids] = parseIds(req.params.id);
|
|
119
|
+
if (isSingle) {
|
|
120
|
+
if (this.disableRemove) {
|
|
121
|
+
throw new Error(`DELETE by single id is disabled on this resource`);
|
|
122
|
+
}
|
|
123
|
+
return core.remove({ params: { id: ids[0] } });
|
|
124
|
+
}
|
|
125
|
+
if (this.disableRemoveMany) {
|
|
126
|
+
throw new Error(`DELETE by multiple ids is disabled on this resource`);
|
|
127
|
+
}
|
|
128
|
+
return core.removeMany({ params: { ids } });
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
export { BaseRestApiCrudController };
|
package/build/esm/DataCache.d.ts
CHANGED
|
@@ -1,16 +1,127 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { DataCachePropsInterface, LoaderInterface } from './interfaces';
|
|
2
|
+
/**
|
|
3
|
+
* DataCache implements LoaderInterface using Facebook's DataLoader for
|
|
4
|
+
* batched, per-request in-memory caching of database records.
|
|
5
|
+
*
|
|
6
|
+
* It is the default loader used by BaseGateway when no custom loader is
|
|
7
|
+
* provided. Each DataCache instance is tied to a single request — DataLoader's
|
|
8
|
+
* cache is intentionally not shared across requests.
|
|
9
|
+
*
|
|
10
|
+
* Two backing strategies are supported:
|
|
11
|
+
* - In-memory DataLoader (default) — per-request cache, no TTL
|
|
12
|
+
* - Redis-backed RedisDataLoader — shared cache with TTL, used when
|
|
13
|
+
* `redisClient` is provided in config
|
|
14
|
+
*
|
|
15
|
+
* Key building:
|
|
16
|
+
* All cache keys are built via the `buildKey` function (defaults to
|
|
17
|
+
* `buildKey` from @sdflc/utils). This ensures consistent key format
|
|
18
|
+
* between `load()`, `loadMany()`, `prime()`, and `clear()` calls.
|
|
19
|
+
*
|
|
20
|
+
* Batch loading:
|
|
21
|
+
* By default, uses `batchLoaderDefault` which issues a single
|
|
22
|
+
* `WHERE idField IN (ids)` query per DataLoader tick. For `readAll: true`,
|
|
23
|
+
* fetches the entire table and maps by id field.
|
|
24
|
+
* A custom `loaderFn` can be provided to replace the default batch function.
|
|
25
|
+
*/
|
|
2
26
|
declare class DataCache implements LoaderInterface {
|
|
3
27
|
private buildKey;
|
|
4
28
|
private loader;
|
|
5
29
|
private config;
|
|
6
30
|
private redisClient;
|
|
7
|
-
constructor(props:
|
|
8
|
-
|
|
31
|
+
constructor(props: DataCachePropsInterface);
|
|
32
|
+
/**
|
|
33
|
+
* Creates the default batch loader function for this DataCache instance.
|
|
34
|
+
*
|
|
35
|
+
* The returned async function is called by DataLoader with an array of
|
|
36
|
+
* keys collected during the current tick (batched). It issues a single
|
|
37
|
+
* `WHERE idField IN (ids)` query and maps results back to the input key
|
|
38
|
+
* order — DataLoader requires results in the same order as input keys,
|
|
39
|
+
* with `null` for any id that was not found.
|
|
40
|
+
*
|
|
41
|
+
* For `readAll: true`, fetches the entire table and returns all rows as
|
|
42
|
+
* a flat array rather than mapping by id.
|
|
43
|
+
*
|
|
44
|
+
* Throws synchronously (at DataCache construction time) if required config
|
|
45
|
+
* is missing — `table`, `idField` (unless `readAll` is set), and `db`.
|
|
46
|
+
*
|
|
47
|
+
* @param props DataCachePropsInterface config, already normalised with idField fallbacks
|
|
48
|
+
*/
|
|
49
|
+
batchLoaderDefault(props: DataCachePropsInterface): (ids: any[]) => Promise<any[]>;
|
|
50
|
+
/**
|
|
51
|
+
* Initialises the underlying DataLoader or RedisDataLoader instance.
|
|
52
|
+
*
|
|
53
|
+
* When `redisClient` is available, uses RedisDataLoader for shared caching
|
|
54
|
+
* across requests with TTL support. The batch function is wrapped in a
|
|
55
|
+
* `{ load }` adapter since RedisDataLoader expects a DataLoader-like interface
|
|
56
|
+
* rather than a raw batch function.
|
|
57
|
+
*
|
|
58
|
+
* When no `redisClient` is available, uses a standard in-memory DataLoader.
|
|
59
|
+
* DataLoader's default options are used (unlimited batch size, caching enabled)
|
|
60
|
+
* which are appropriate for per-request instances.
|
|
61
|
+
*
|
|
62
|
+
* The `context` parameter is passed through to the batch function for use
|
|
63
|
+
* by custom `loaderFn` implementations — the default batch loader ignores it.
|
|
64
|
+
*
|
|
65
|
+
* @param batchFunction Async function receiving an array of keys, returning results in the same order
|
|
66
|
+
* @param keyPrefix Optional namespace prefix for Redis keys
|
|
67
|
+
* @param context Request context passed to the batch function
|
|
68
|
+
*/
|
|
9
69
|
init(batchFunction: any, keyPrefix?: string, context?: any): void;
|
|
10
|
-
|
|
11
|
-
|
|
70
|
+
/**
|
|
71
|
+
* Loads a single record by key.
|
|
72
|
+
*
|
|
73
|
+
* Returns null immediately if `key` is null or undefined — avoids
|
|
74
|
+
* passing invalid keys to the underlying loader or buildKey function.
|
|
75
|
+
*
|
|
76
|
+
* Fix: was checking `builtKey == null` after calling buildKey, but
|
|
77
|
+
* buildKey always returns a string (e.g. 'null') for null input.
|
|
78
|
+
* The guard now checks the input key directly.
|
|
79
|
+
*
|
|
80
|
+
* @param key The record id (before key building)
|
|
81
|
+
*/
|
|
82
|
+
load(key: any): Promise<any>;
|
|
83
|
+
/**
|
|
84
|
+
* Loads multiple records by their keys in a single batched call.
|
|
85
|
+
*
|
|
86
|
+
* Null/undefined keys in the array are passed through as null rather
|
|
87
|
+
* than being sent to buildKey (which would produce a 'null' string key).
|
|
88
|
+
* DataLoader preserves result order, so null inputs produce null outputs
|
|
89
|
+
* at the same index.
|
|
90
|
+
*
|
|
91
|
+
* @param keys Array of record ids (before key building)
|
|
92
|
+
*/
|
|
93
|
+
loadMany(keys: any[]): Promise<any[]>;
|
|
94
|
+
/**
|
|
95
|
+
* Primes the cache with a known value for the given key.
|
|
96
|
+
* Useful after a create() or update() to seed the cache without
|
|
97
|
+
* requiring a subsequent load() round-trip.
|
|
98
|
+
*
|
|
99
|
+
* Returns `this` for chaining.
|
|
100
|
+
*
|
|
101
|
+
* @param key The record id (before key building)
|
|
102
|
+
* @param value The value to cache
|
|
103
|
+
*/
|
|
12
104
|
prime(key: any, value: any): this;
|
|
105
|
+
/**
|
|
106
|
+
* Clears the cached value for one or more keys.
|
|
107
|
+
* Accepts either a single key or an array of keys.
|
|
108
|
+
*
|
|
109
|
+
* Called by BaseGateway after update(), updateMany(), increment(),
|
|
110
|
+
* decrement(), and remove() to ensure stale records are not served
|
|
111
|
+
* from cache on subsequent load() calls within the same request.
|
|
112
|
+
*
|
|
113
|
+
* Returns `this` for chaining.
|
|
114
|
+
*
|
|
115
|
+
* @param key A single record id or an array of record ids
|
|
116
|
+
*/
|
|
13
117
|
clear(key: any | any[]): this;
|
|
118
|
+
/**
|
|
119
|
+
* Clears all cached values from the loader.
|
|
120
|
+
* Rarely needed in normal operation — useful in tests or when a bulk
|
|
121
|
+
* operation has invalidated an unknown set of records.
|
|
122
|
+
*
|
|
123
|
+
* Returns `this` for chaining.
|
|
124
|
+
*/
|
|
14
125
|
clearAll(): this;
|
|
15
126
|
}
|
|
16
127
|
export { DataCache };
|
package/build/esm/DataCache.js
CHANGED
|
@@ -1,8 +1,33 @@
|
|
|
1
|
+
// ./src/DataCache.ts
|
|
1
2
|
import DataLoader from 'dataloader';
|
|
2
|
-
import { RedisDataLoader } from './RedisDataLoader';
|
|
3
|
-
import { buildKey as defaultBuildKey } from '@sdflc/utils';
|
|
4
|
-
import { FIELDS } from '.';
|
|
5
3
|
import { castArray } from 'lodash';
|
|
4
|
+
import { buildKey as defaultBuildKey } from '@sdflc/utils';
|
|
5
|
+
import { RedisDataLoader } from './RedisDataLoader';
|
|
6
|
+
import { FIELDS } from './constants';
|
|
7
|
+
/**
|
|
8
|
+
* DataCache implements LoaderInterface using Facebook's DataLoader for
|
|
9
|
+
* batched, per-request in-memory caching of database records.
|
|
10
|
+
*
|
|
11
|
+
* It is the default loader used by BaseGateway when no custom loader is
|
|
12
|
+
* provided. Each DataCache instance is tied to a single request — DataLoader's
|
|
13
|
+
* cache is intentionally not shared across requests.
|
|
14
|
+
*
|
|
15
|
+
* Two backing strategies are supported:
|
|
16
|
+
* - In-memory DataLoader (default) — per-request cache, no TTL
|
|
17
|
+
* - Redis-backed RedisDataLoader — shared cache with TTL, used when
|
|
18
|
+
* `redisClient` is provided in config
|
|
19
|
+
*
|
|
20
|
+
* Key building:
|
|
21
|
+
* All cache keys are built via the `buildKey` function (defaults to
|
|
22
|
+
* `buildKey` from @sdflc/utils). This ensures consistent key format
|
|
23
|
+
* between `load()`, `loadMany()`, `prime()`, and `clear()` calls.
|
|
24
|
+
*
|
|
25
|
+
* Batch loading:
|
|
26
|
+
* By default, uses `batchLoaderDefault` which issues a single
|
|
27
|
+
* `WHERE idField IN (ids)` query per DataLoader tick. For `readAll: true`,
|
|
28
|
+
* fetches the entire table and maps by id field.
|
|
29
|
+
* A custom `loaderFn` can be provided to replace the default batch function.
|
|
30
|
+
*/
|
|
6
31
|
class DataCache {
|
|
7
32
|
buildKey;
|
|
8
33
|
loader;
|
|
@@ -10,6 +35,7 @@ class DataCache {
|
|
|
10
35
|
redisClient;
|
|
11
36
|
constructor(props) {
|
|
12
37
|
const { loaderFn, keyPrefix, context, buildKey, redisClient, table } = props || {};
|
|
38
|
+
// Normalise idField and idFieldAs with fallbacks to the standard id field
|
|
13
39
|
const innerProps = {
|
|
14
40
|
...props,
|
|
15
41
|
idField: props?.idField || FIELDS.ID,
|
|
@@ -18,21 +44,43 @@ class DataCache {
|
|
|
18
44
|
this.config = innerProps;
|
|
19
45
|
this.redisClient = redisClient;
|
|
20
46
|
this.buildKey = typeof buildKey === 'function' ? buildKey : defaultBuildKey;
|
|
21
|
-
|
|
47
|
+
// Use a custom loader function if provided, otherwise create the default
|
|
48
|
+
// batch loader. The default loader throws synchronously here if required
|
|
49
|
+
// config (table, idField, db) is missing — fail fast at construction time.
|
|
22
50
|
const fn = typeof loaderFn === 'function' ? loaderFn : this.batchLoaderDefault(innerProps);
|
|
51
|
+
// keyPrefix scopes DataLoader cache keys to avoid collisions between
|
|
52
|
+
// different resources sharing the same Redis instance or request context.
|
|
53
|
+
// Resolution order: context.keyPrefix → config.keyPrefix → table name
|
|
23
54
|
const prefixToUse = context?.keyPrefix || keyPrefix || table;
|
|
24
55
|
this.init(fn, prefixToUse, context);
|
|
25
56
|
}
|
|
57
|
+
/**
|
|
58
|
+
* Creates the default batch loader function for this DataCache instance.
|
|
59
|
+
*
|
|
60
|
+
* The returned async function is called by DataLoader with an array of
|
|
61
|
+
* keys collected during the current tick (batched). It issues a single
|
|
62
|
+
* `WHERE idField IN (ids)` query and maps results back to the input key
|
|
63
|
+
* order — DataLoader requires results in the same order as input keys,
|
|
64
|
+
* with `null` for any id that was not found.
|
|
65
|
+
*
|
|
66
|
+
* For `readAll: true`, fetches the entire table and returns all rows as
|
|
67
|
+
* a flat array rather than mapping by id.
|
|
68
|
+
*
|
|
69
|
+
* Throws synchronously (at DataCache construction time) if required config
|
|
70
|
+
* is missing — `table`, `idField` (unless `readAll` is set), and `db`.
|
|
71
|
+
*
|
|
72
|
+
* @param props DataCachePropsInterface config, already normalised with idField fallbacks
|
|
73
|
+
*/
|
|
26
74
|
batchLoaderDefault(props) {
|
|
27
75
|
const { table, idField, idFieldAs, readAll, db } = props;
|
|
28
76
|
if (!table) {
|
|
29
|
-
throw Error(`DataCache requires 'table' property to be
|
|
77
|
+
throw new Error(`DataCache requires 'table' property to be set up`);
|
|
30
78
|
}
|
|
31
|
-
|
|
32
|
-
throw Error(`DataCache requires 'idField' or 'readAll' property to be
|
|
79
|
+
if (!idField && readAll == null) {
|
|
80
|
+
throw new Error(`DataCache requires 'idField' or 'readAll' property to be set up`);
|
|
33
81
|
}
|
|
34
|
-
|
|
35
|
-
throw Error(`DataCache requires 'db' property to be
|
|
82
|
+
if (!db) {
|
|
83
|
+
throw new Error(`DataCache requires 'db' property to be set up`);
|
|
36
84
|
}
|
|
37
85
|
return async (ids) => {
|
|
38
86
|
const resultItems = [];
|
|
@@ -42,29 +90,53 @@ class DataCache {
|
|
|
42
90
|
};
|
|
43
91
|
const idsToUse = castArray(ids);
|
|
44
92
|
if (!readAll) {
|
|
93
|
+
// Map results by id so we can look them up in key order below.
|
|
94
|
+
// idFieldAs allows the query to alias the id column if it differs
|
|
95
|
+
// from the column name used for lookup (e.g. join scenarios).
|
|
45
96
|
readCfg.mapBy = idFieldAs || idField;
|
|
46
97
|
readCfg.whereIn = {
|
|
47
98
|
field: idField,
|
|
48
|
-
|
|
99
|
+
// Fix: use != null instead of truthy check so integer id 0 is not filtered out
|
|
100
|
+
values: idsToUse.filter((id) => id != null),
|
|
49
101
|
};
|
|
50
102
|
}
|
|
51
103
|
const dbItems = await db.read(readCfg);
|
|
52
104
|
if (readAll) {
|
|
105
|
+
// readAll mode: no mapBy set so db.read() returns any[]
|
|
53
106
|
resultItems.push(...dbItems);
|
|
54
107
|
}
|
|
55
108
|
else {
|
|
56
|
-
|
|
109
|
+
// mapBy is set so db.read() returns Record<string, any>
|
|
110
|
+
const mappedItems = dbItems;
|
|
111
|
+
resultItems.push(...idsToUse.map((id) => mappedItems[this.buildKey(id)] || null));
|
|
57
112
|
}
|
|
58
113
|
return resultItems;
|
|
59
114
|
};
|
|
60
115
|
}
|
|
116
|
+
/**
|
|
117
|
+
* Initialises the underlying DataLoader or RedisDataLoader instance.
|
|
118
|
+
*
|
|
119
|
+
* When `redisClient` is available, uses RedisDataLoader for shared caching
|
|
120
|
+
* across requests with TTL support. The batch function is wrapped in a
|
|
121
|
+
* `{ load }` adapter since RedisDataLoader expects a DataLoader-like interface
|
|
122
|
+
* rather than a raw batch function.
|
|
123
|
+
*
|
|
124
|
+
* When no `redisClient` is available, uses a standard in-memory DataLoader.
|
|
125
|
+
* DataLoader's default options are used (unlimited batch size, caching enabled)
|
|
126
|
+
* which are appropriate for per-request instances.
|
|
127
|
+
*
|
|
128
|
+
* The `context` parameter is passed through to the batch function for use
|
|
129
|
+
* by custom `loaderFn` implementations — the default batch loader ignores it.
|
|
130
|
+
*
|
|
131
|
+
* @param batchFunction Async function receiving an array of keys, returning results in the same order
|
|
132
|
+
* @param keyPrefix Optional namespace prefix for Redis keys
|
|
133
|
+
* @param context Request context passed to the batch function
|
|
134
|
+
*/
|
|
61
135
|
init(batchFunction, keyPrefix, context) {
|
|
62
136
|
if (this.redisClient) {
|
|
63
|
-
this.loader = new RedisDataLoader(this.redisClient,
|
|
64
|
-
//
|
|
65
|
-
//
|
|
66
|
-
keyPrefix,
|
|
67
|
-
// create a regular loader. This should always be set with caching disabled.
|
|
137
|
+
this.loader = new RedisDataLoader(this.redisClient, keyPrefix,
|
|
138
|
+
// RedisDataLoader expects a DataLoader-like object with a `load` method,
|
|
139
|
+
// not a raw batch function — wrap accordingly
|
|
68
140
|
{
|
|
69
141
|
load: (ids) => batchFunction(ids, context),
|
|
70
142
|
}, {
|
|
@@ -76,20 +148,63 @@ class DataCache {
|
|
|
76
148
|
this.loader = new DataLoader((ids) => batchFunction(ids, context));
|
|
77
149
|
}
|
|
78
150
|
}
|
|
151
|
+
/**
|
|
152
|
+
* Loads a single record by key.
|
|
153
|
+
*
|
|
154
|
+
* Returns null immediately if `key` is null or undefined — avoids
|
|
155
|
+
* passing invalid keys to the underlying loader or buildKey function.
|
|
156
|
+
*
|
|
157
|
+
* Fix: was checking `builtKey == null` after calling buildKey, but
|
|
158
|
+
* buildKey always returns a string (e.g. 'null') for null input.
|
|
159
|
+
* The guard now checks the input key directly.
|
|
160
|
+
*
|
|
161
|
+
* @param key The record id (before key building)
|
|
162
|
+
*/
|
|
79
163
|
load(key) {
|
|
80
|
-
|
|
81
|
-
if (builtKey == null) {
|
|
164
|
+
if (key == null) {
|
|
82
165
|
return Promise.resolve(null);
|
|
83
166
|
}
|
|
84
|
-
return this.loader.load(
|
|
167
|
+
return this.loader.load(this.buildKey(key));
|
|
85
168
|
}
|
|
169
|
+
/**
|
|
170
|
+
* Loads multiple records by their keys in a single batched call.
|
|
171
|
+
*
|
|
172
|
+
* Null/undefined keys in the array are passed through as null rather
|
|
173
|
+
* than being sent to buildKey (which would produce a 'null' string key).
|
|
174
|
+
* DataLoader preserves result order, so null inputs produce null outputs
|
|
175
|
+
* at the same index.
|
|
176
|
+
*
|
|
177
|
+
* @param keys Array of record ids (before key building)
|
|
178
|
+
*/
|
|
86
179
|
loadMany(keys) {
|
|
87
|
-
return this.loader.loadMany(keys.map((key) => this.buildKey(key)));
|
|
180
|
+
return this.loader.loadMany(keys.map((key) => (key != null ? this.buildKey(key) : null)));
|
|
88
181
|
}
|
|
182
|
+
/**
|
|
183
|
+
* Primes the cache with a known value for the given key.
|
|
184
|
+
* Useful after a create() or update() to seed the cache without
|
|
185
|
+
* requiring a subsequent load() round-trip.
|
|
186
|
+
*
|
|
187
|
+
* Returns `this` for chaining.
|
|
188
|
+
*
|
|
189
|
+
* @param key The record id (before key building)
|
|
190
|
+
* @param value The value to cache
|
|
191
|
+
*/
|
|
89
192
|
prime(key, value) {
|
|
90
193
|
this.loader?.prime(this.buildKey(key), value);
|
|
91
194
|
return this;
|
|
92
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* Clears the cached value for one or more keys.
|
|
198
|
+
* Accepts either a single key or an array of keys.
|
|
199
|
+
*
|
|
200
|
+
* Called by BaseGateway after update(), updateMany(), increment(),
|
|
201
|
+
* decrement(), and remove() to ensure stale records are not served
|
|
202
|
+
* from cache on subsequent load() calls within the same request.
|
|
203
|
+
*
|
|
204
|
+
* Returns `this` for chaining.
|
|
205
|
+
*
|
|
206
|
+
* @param key A single record id or an array of record ids
|
|
207
|
+
*/
|
|
93
208
|
clear(key) {
|
|
94
209
|
if (Array.isArray(key)) {
|
|
95
210
|
key.forEach((item) => this.loader?.clear(this.buildKey(item)));
|
|
@@ -99,6 +214,13 @@ class DataCache {
|
|
|
99
214
|
}
|
|
100
215
|
return this;
|
|
101
216
|
}
|
|
217
|
+
/**
|
|
218
|
+
* Clears all cached values from the loader.
|
|
219
|
+
* Rarely needed in normal operation — useful in tests or when a bulk
|
|
220
|
+
* operation has invalidated an unknown set of records.
|
|
221
|
+
*
|
|
222
|
+
* Returns `this` for chaining.
|
|
223
|
+
*/
|
|
102
224
|
clearAll() {
|
|
103
225
|
this.loader?.clearAll();
|
|
104
226
|
return this;
|