@sdflc/backend-helpers 1.0.112 → 1.0.113

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.
Files changed (206) hide show
  1. package/README.md +1422 -146
  2. package/build/BaseController.d.ts +20 -0
  3. package/build/BaseController.js +64 -0
  4. package/build/BaseCore.d.ts +470 -33
  5. package/build/BaseCore.js +608 -127
  6. package/build/BaseExternalApiGateway.d.ts +16 -0
  7. package/build/BaseExternalApiGateway.js +54 -0
  8. package/build/BaseGateway.d.ts +455 -17
  9. package/build/BaseGateway.js +502 -56
  10. package/build/BaseRestApiCrudController.d.ts +37 -0
  11. package/build/BaseRestApiCrudController.js +134 -0
  12. package/build/DataCache.d.ts +116 -5
  13. package/build/DataCache.js +144 -22
  14. package/build/Database.d.ts +165 -4
  15. package/build/Database.js +224 -51
  16. package/build/DbMigratorAndSeeder.d.ts +127 -26
  17. package/build/DbMigratorAndSeeder.js +180 -69
  18. package/build/RedisDataLoader.d.ts +144 -21
  19. package/build/RedisDataLoader.js +178 -49
  20. package/build/apiContext.d.ts +0 -8
  21. package/build/apiContext.js +12 -27
  22. package/build/checkItHelpers.d.ts +32 -0
  23. package/build/checkItHelpers.js +73 -7
  24. package/build/commonValidators.d.ts +107 -16
  25. package/build/commonValidators.js +211 -106
  26. package/build/configBuilder.d.ts +23 -0
  27. package/build/configBuilder.js +73 -0
  28. package/build/constants.d.ts +134 -17
  29. package/build/constants.js +95 -15
  30. package/build/dbHelpers.d.ts +89 -29
  31. package/build/dbHelpers.js +175 -86
  32. package/build/dbSeeder.d.ts +10 -1
  33. package/build/dbSeeder.js +80 -15
  34. package/build/dbTableHelpers.d.ts +122 -5
  35. package/build/dbTableHelpers.js +151 -13
  36. package/build/downloadHelpers.d.ts +24 -1
  37. package/build/downloadHelpers.js +51 -21
  38. package/build/esm/BaseController.d.ts +20 -0
  39. package/build/esm/BaseController.js +58 -0
  40. package/build/esm/BaseCore.d.ts +470 -33
  41. package/build/esm/BaseCore.js +599 -118
  42. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  43. package/build/esm/BaseExternalApiGateway.js +48 -0
  44. package/build/esm/BaseGateway.d.ts +455 -17
  45. package/build/esm/BaseGateway.js +503 -57
  46. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  47. package/build/esm/BaseRestApiCrudController.js +131 -0
  48. package/build/esm/DataCache.d.ts +116 -5
  49. package/build/esm/DataCache.js +142 -20
  50. package/build/esm/Database.d.ts +165 -4
  51. package/build/esm/Database.js +224 -51
  52. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  53. package/build/esm/DbMigratorAndSeeder.js +184 -71
  54. package/build/esm/RedisDataLoader.d.ts +144 -21
  55. package/build/esm/RedisDataLoader.js +179 -50
  56. package/build/esm/apiContext.d.ts +0 -8
  57. package/build/esm/apiContext.js +12 -27
  58. package/build/esm/checkItHelpers.d.ts +32 -0
  59. package/build/esm/checkItHelpers.js +73 -7
  60. package/build/esm/commonValidators.d.ts +107 -16
  61. package/build/esm/commonValidators.js +209 -105
  62. package/build/esm/configBuilder.d.ts +23 -0
  63. package/build/esm/configBuilder.js +69 -0
  64. package/build/esm/constants.d.ts +134 -17
  65. package/build/esm/constants.js +94 -14
  66. package/build/esm/dbHelpers.d.ts +89 -29
  67. package/build/esm/dbHelpers.js +171 -81
  68. package/build/esm/dbSeeder.d.ts +10 -1
  69. package/build/esm/dbSeeder.js +81 -16
  70. package/build/esm/dbTableHelpers.d.ts +122 -5
  71. package/build/esm/dbTableHelpers.js +152 -14
  72. package/build/esm/downloadHelpers.d.ts +24 -1
  73. package/build/esm/downloadHelpers.js +51 -21
  74. package/build/esm/index.d.ts +5 -2
  75. package/build/esm/index.js +5 -2
  76. package/build/esm/interfaces/ApiContext.d.ts +7 -3
  77. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  78. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  79. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  80. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  81. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  82. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +87 -9
  83. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  84. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  85. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  86. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  87. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  88. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  89. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  90. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  91. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  92. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  93. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  94. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  95. package/build/esm/interfaces/CacheInterface.js +1 -0
  96. package/build/esm/interfaces/CoreActionInterface.d.ts +20 -0
  97. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  98. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  99. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  100. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  101. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  102. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  103. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  104. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  105. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  106. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  107. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  108. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  109. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  110. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  111. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  112. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  113. package/build/esm/interfaces/LoaderInterface.js +1 -0
  114. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  115. package/build/esm/interfaces/UserTokenParams.js +1 -0
  116. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  117. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  118. package/build/esm/interfaces/index.d.ts +4 -0
  119. package/build/esm/interfaces/index.js +4 -0
  120. package/build/esm/knexConfigBuilder.d.ts +25 -0
  121. package/build/esm/knexConfigBuilder.js +100 -36
  122. package/build/esm/parseIds.d.ts +6 -0
  123. package/build/esm/parseIds.js +13 -0
  124. package/build/esm/passwordHelpers.d.ts +22 -0
  125. package/build/esm/passwordHelpers.js +40 -8
  126. package/build/esm/redisClient.d.ts +57 -4
  127. package/build/esm/redisClient.js +40 -54
  128. package/build/esm/resolveClientIp.d.ts +15 -0
  129. package/build/esm/resolveClientIp.js +34 -0
  130. package/build/esm/resolversHelpers.d.ts +21 -1
  131. package/build/esm/resolversHelpers.js +48 -26
  132. package/build/esm/userToken.d.ts +50 -1
  133. package/build/esm/userToken.js +85 -20
  134. package/build/esm/utils.d.ts +20 -2
  135. package/build/esm/utils.js +23 -13
  136. package/build/index.d.ts +5 -2
  137. package/build/index.js +5 -2
  138. package/build/interfaces/ApiContext.d.ts +7 -3
  139. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  140. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  141. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  142. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  143. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  144. package/build/interfaces/BaseCorePropsInterface.d.ts +87 -9
  145. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  146. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  147. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  148. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  149. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  150. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  151. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  152. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  153. package/build/interfaces/BuildConfigOptions.js +1 -0
  154. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  155. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  156. package/build/interfaces/CacheInterface.d.ts +18 -1
  157. package/build/interfaces/CacheInterface.js +1 -0
  158. package/build/interfaces/CoreActionInterface.d.ts +20 -0
  159. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  160. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  161. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  162. package/build/interfaces/DataCachePropsInterface.js +3 -0
  163. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  164. package/build/interfaces/DatabaseOptions.js +1 -0
  165. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  166. package/build/interfaces/DatabaseReadInterface.js +1 -0
  167. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  168. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  169. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  170. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  171. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  172. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  173. package/build/interfaces/ListArgsInterface.js +1 -0
  174. package/build/interfaces/LoaderInterface.d.ts +36 -1
  175. package/build/interfaces/LoaderInterface.js +1 -0
  176. package/build/interfaces/UserTokenParams.d.ts +23 -5
  177. package/build/interfaces/UserTokenParams.js +1 -0
  178. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  179. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  180. package/build/interfaces/index.d.ts +4 -0
  181. package/build/interfaces/index.js +4 -0
  182. package/build/knexConfigBuilder.d.ts +25 -0
  183. package/build/knexConfigBuilder.js +99 -35
  184. package/build/parseIds.d.ts +6 -0
  185. package/build/parseIds.js +17 -0
  186. package/build/passwordHelpers.d.ts +22 -0
  187. package/build/passwordHelpers.js +40 -8
  188. package/build/redisClient.d.ts +57 -4
  189. package/build/redisClient.js +40 -54
  190. package/build/resolveClientIp.d.ts +15 -0
  191. package/build/resolveClientIp.js +38 -0
  192. package/build/resolversHelpers.d.ts +21 -1
  193. package/build/resolversHelpers.js +48 -26
  194. package/build/userToken.d.ts +50 -1
  195. package/build/userToken.js +85 -20
  196. package/build/utils.d.ts +20 -2
  197. package/build/utils.js +24 -16
  198. package/package.json +19 -18
  199. package/build/baseController.d.ts +0 -17
  200. package/build/baseController.js +0 -64
  201. package/build/configBulder.d.ts +0 -2
  202. package/build/configBulder.js +0 -36
  203. package/build/esm/baseController.d.ts +0 -17
  204. package/build/esm/baseController.js +0 -58
  205. package/build/esm/configBulder.d.ts +0 -2
  206. 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 };
@@ -1,16 +1,127 @@
1
- import { CacheInterface, LoaderInterface } from './interfaces';
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: CacheInterface);
8
- batchLoaderDefault(props: CacheInterface): (ids: any[]) => Promise<any[]>;
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
- load(key: any): any;
11
- loadMany(keys: any[]): any;
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 };
@@ -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
- this.batchLoaderDefault = this.batchLoaderDefault.bind(this);
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 setup`);
77
+ throw new Error(`DataCache requires 'table' property to be set up`);
30
78
  }
31
- else if (!idField && readAll == null) {
32
- throw Error(`DataCache requires 'idField' or 'readAll' property to be setup`);
79
+ if (!idField && readAll == null) {
80
+ throw new Error(`DataCache requires 'idField' or 'readAll' property to be set up`);
33
81
  }
34
- else if (!db) {
35
- throw Error(`DataCache requires 'db' property to be setup`);
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
- values: idsToUse.filter((id) => id),
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
- resultItems.push(...idsToUse.map((id) => dbItems[this.buildKey(id)] || null));
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
- // set a prefix for the keys stored in redis. This way you can avoid key
65
- // collisions for different data-sets in your redis instance.
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
- const builtKey = this.buildKey(key);
81
- if (builtKey == null) {
164
+ if (key == null) {
82
165
  return Promise.resolve(null);
83
166
  }
84
- return this.loader.load(builtKey);
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;