@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
@@ -1,3 +1,4 @@
1
+ // ./src/commonValidators.ts
1
2
  import { castArray } from 'lodash';
2
3
  import Checkit from 'checkit';
3
4
  import check from 'check-types';
@@ -5,52 +6,51 @@ import isUUID from 'is-uuid';
5
6
  import { OpResult, OP_RESULT_CODES } from '@sdflc/api-helpers';
6
7
  import { createErrorOnCheckError } from './checkItHelpers';
7
8
  import { ID_TYPES } from './constants';
9
+ // ─── Checkit rule sets ────────────────────────────────────────────────────────
10
+ // Defined once at module level and reused across all validator calls.
11
+ // Each rule set is a Checkit instance — stateless and safe to share.
12
+ /**
13
+ * Validates that `args.id` is present and is an integer.
14
+ * Used by validateGet and validateRemove when idType is ID_TYPES.INT.
15
+ */
8
16
  const rulesSingleIntId = new Checkit({
9
17
  id: [
10
- {
11
- rule: 'required',
12
- message: 'ID is required',
13
- },
14
- {
15
- rule: 'integer',
16
- message: 'ID should be an integer',
17
- },
18
+ { rule: 'required', message: 'ID is required' },
19
+ { rule: 'integer', message: 'ID should be an integer' },
18
20
  ],
19
21
  });
22
+ /**
23
+ * Validates that `args.id` is present and is a valid UUID v4.
24
+ * Used by validateGet and validateRemove when idType is ID_TYPES.UUID.
25
+ *
26
+ * Fix: error message was incorrectly saying 'ID should be an integer'.
27
+ */
20
28
  const rulesSingleUuidId = new Checkit({
21
29
  id: [
22
- {
23
- rule: 'required',
24
- message: 'ID is required',
25
- },
26
- {
27
- rule: 'uuid',
28
- message: 'ID should be an integer',
29
- },
30
+ { rule: 'required', message: 'ID is required' },
31
+ { rule: 'uuid', message: 'ID should be a UUID' },
30
32
  ],
31
33
  });
34
+ /**
35
+ * Validates that `args.id` is present and is a non-empty string.
36
+ * Used by validateGet and validateRemove when idType is ID_TYPES.TEXT.
37
+ */
32
38
  const rulesSingleTextId = new Checkit({
33
39
  id: [
34
- {
35
- rule: 'required',
36
- message: 'ID is required',
37
- },
38
- {
39
- rule: 'string',
40
- message: 'ID should be a string',
41
- },
40
+ { rule: 'required', message: 'ID is required' },
41
+ { rule: 'string', message: 'ID should be a string' },
42
42
  ],
43
43
  });
44
+ /**
45
+ * Validates that `args.ids` is present, is an array, and every element
46
+ * is an integer. The custom rule throws an OpResult on failure so checkit
47
+ * can surface per-item errors.
48
+ * Used by validateGetMany and validateRemoveMany when idType is ID_TYPES.INT.
49
+ */
44
50
  const rulesMultipleIntIds = new Checkit({
45
51
  ids: [
46
- {
47
- rule: 'required',
48
- message: 'IDs is required',
49
- },
50
- {
51
- rule: 'array',
52
- message: 'IDs should be an array of integer',
53
- },
52
+ { rule: 'required', message: 'IDs is required' },
53
+ { rule: 'array', message: 'IDs should be an array of integers' },
54
54
  {
55
55
  rule: (values) => {
56
56
  const opResult = new OpResult();
@@ -67,16 +67,15 @@ const rulesMultipleIntIds = new Checkit({
67
67
  },
68
68
  ],
69
69
  });
70
+ /**
71
+ * Validates that `args.ids` is present, is an array, and every element
72
+ * is a valid UUID v4. The custom rule throws an OpResult on failure.
73
+ * Used by validateGetMany and validateRemoveMany when idType is ID_TYPES.UUID.
74
+ */
70
75
  const rulesMultipleUuidIds = new Checkit({
71
76
  ids: [
72
- {
73
- rule: 'required',
74
- message: 'IDs is required',
75
- },
76
- {
77
- rule: 'array',
78
- message: 'IDs should be an array of UUIDs',
79
- },
77
+ { rule: 'required', message: 'IDs is required' },
78
+ { rule: 'array', message: 'IDs should be an array of UUIDs' },
80
79
  {
81
80
  rule: (values) => {
82
81
  const opResult = new OpResult();
@@ -93,16 +92,15 @@ const rulesMultipleUuidIds = new Checkit({
93
92
  },
94
93
  ],
95
94
  });
95
+ /**
96
+ * Validates that `args.ids` is present, is an array, and every element
97
+ * is a non-empty string. The custom rule throws an OpResult on failure.
98
+ * Used by validateGetMany and validateRemoveMany when idType is ID_TYPES.TEXT.
99
+ */
96
100
  const rulesMultipleTextIds = new Checkit({
97
101
  ids: [
98
- {
99
- rule: 'required',
100
- message: 'IDs is required',
101
- },
102
- {
103
- rule: 'array',
104
- message: 'IDs should be an array of strings',
105
- },
102
+ { rule: 'required', message: 'IDs is required' },
103
+ { rule: 'array', message: 'IDs should be an array of strings' },
106
104
  {
107
105
  rule: (values) => {
108
106
  const opResult = new OpResult();
@@ -119,66 +117,115 @@ const rulesMultipleTextIds = new Checkit({
119
117
  },
120
118
  ],
121
119
  });
120
+ // ─── Shared guard helpers ─────────────────────────────────────────────────────
121
+ /**
122
+ * Guards that `args` is a non-empty plain object.
123
+ * Returns `[result]` where result is a failed OpResult if the check fails,
124
+ * or `[true]` if it passes.
125
+ *
126
+ * Fix: added explicit object type check before Object.keys() to correctly
127
+ * reject non-objects (null, numbers, strings) rather than treating them
128
+ * as empty objects.
129
+ */
122
130
  export const shouldHaveParams = (args) => {
123
- const keys = Object.keys(args || {});
124
- if (keys.length === 0) {
131
+ if (!check.object(args) || Object.keys(args).length === 0) {
125
132
  const result = new OpResult({ code: OP_RESULT_CODES.VALIDATION_FAILED });
126
133
  result.addError('', 'No params received');
127
134
  return [result];
128
135
  }
129
136
  return [true];
130
137
  };
138
+ /**
139
+ * Guards that `id` is a non-null, non-empty value.
140
+ * Returns `[result]` where result is a failed OpResult if the check fails,
141
+ * or `[true]` if it passes.
142
+ *
143
+ * Fix: replaced falsy check `!id` with explicit null/empty-string check
144
+ * so that `id = 0` (a valid integer id) is not incorrectly rejected.
145
+ */
131
146
  export const shouldHaveId = (id) => {
132
- if (!id) {
147
+ if (id == null || id === '') {
133
148
  const result = new OpResult({ code: OP_RESULT_CODES.VALIDATION_FAILED });
134
149
  result.addError('', 'ID is required');
135
150
  return [result];
136
151
  }
137
152
  return [true];
138
153
  };
139
- export const validateSingleIntId = async (args, opt) => {
154
+ // ─── Typed single-id validators ───────────────────────────────────────────────
155
+ // These are used directly when the id type is known at call site.
156
+ // For type-aware validation that reads idType from the core, use
157
+ // validateGet / validateGetMany / validateRemove / validateRemoveMany instead.
158
+ /**
159
+ * Validates that `args.id` is a present integer.
160
+ */
161
+ export const validateSingleIntId = async (args, _opt) => {
140
162
  const [result] = rulesSingleIntId.validateSync(args);
141
163
  if (result) {
142
164
  return [createErrorOnCheckError(result)];
143
165
  }
144
166
  return [true, {}];
145
167
  };
146
- export const validateSingleUuidId = async (args, opt) => {
168
+ /**
169
+ * Validates that `args.id` is a present UUID v4.
170
+ */
171
+ export const validateSingleUuidId = async (args, _opt) => {
147
172
  const [result] = rulesSingleUuidId.validateSync(args);
148
173
  if (result) {
149
174
  return [createErrorOnCheckError(result)];
150
175
  }
151
176
  return [true, {}];
152
177
  };
153
- export const validateSingleTextId = async (args, opt) => {
178
+ /**
179
+ * Validates that `args.id` is a present non-empty string.
180
+ */
181
+ export const validateSingleTextId = async (args, _opt) => {
154
182
  const [result] = rulesSingleTextId.validateSync(args);
155
183
  if (result) {
156
184
  return [createErrorOnCheckError(result)];
157
185
  }
158
186
  return [true, {}];
159
187
  };
160
- export const validateMultipleIntIds = async (args, opt) => {
188
+ /**
189
+ * Validates that `args.ids` is a present array of integers.
190
+ */
191
+ export const validateMultipleIntIds = async (args, _opt) => {
161
192
  const [result] = rulesMultipleIntIds.validateSync(args);
162
193
  if (result) {
163
194
  return [createErrorOnCheckError(result)];
164
195
  }
165
196
  return [true, {}];
166
197
  };
167
- export const validateMultipleUuidIds = async (args, opt) => {
198
+ /**
199
+ * Validates that `args.ids` is a present array of UUID v4 values.
200
+ */
201
+ export const validateMultipleUuidIds = async (args, _opt) => {
168
202
  const [result] = rulesMultipleUuidIds.validateSync(args);
169
203
  if (result) {
170
204
  return [createErrorOnCheckError(result)];
171
205
  }
172
206
  return [true, {}];
173
207
  };
174
- export const validateMultipleTextIds = async (args, opt) => {
208
+ /**
209
+ * Validates that `args.ids` is a present array of non-empty strings.
210
+ */
211
+ export const validateMultipleTextIds = async (args, _opt) => {
175
212
  const [result] = rulesMultipleTextIds.validateSync(args);
176
213
  if (result) {
177
214
  return [createErrorOnCheckError(result)];
178
215
  }
179
216
  return [true, {}];
180
217
  };
181
- export const validateList = ({ rules }) => async (args, opt) => {
218
+ // ─── Context-aware validators ─────────────────────────────────────────────────
219
+ // These read idType from the core instance and select the appropriate
220
+ // rule set automatically. Used as default validators in BaseCore.
221
+ /**
222
+ * Validates list filter args using caller-provided rules.
223
+ * Validates `args.filter` rather than `args` directly.
224
+ *
225
+ * Returns a factory function — call with `{ rules }` to get the validator:
226
+ * `validate: validateList({ rules: myCheckitRules })`
227
+ */
228
+ export const validateList = ({ rules }) => async (args, _opt) => {
182
229
  const { filter } = args || {};
183
230
  const [result] = rules.validateSync(filter);
184
231
  if (result) {
@@ -186,29 +233,31 @@ export const validateList = ({ rules }) => async (args, opt) => {
186
233
  }
187
234
  return [true, {}];
188
235
  };
236
+ /**
237
+ * Validates `args` for a get() call using the core's configured idType.
238
+ * Selects the appropriate single-id rule set (int, UUID, or text).
239
+ * Returns `[true, {}]` immediately if idType is ID_TYPES.UNKNOWN or not set,
240
+ * allowing untyped cores to skip id validation.
241
+ */
189
242
  export const validateGet = async (args, opt) => {
190
243
  const idType = opt.core.getIdType();
191
- let rules = null;
192
244
  switch (idType) {
193
245
  case ID_TYPES.INT:
194
- rules = rulesSingleIntId;
195
- break;
246
+ return runSingleIdValidation(rulesSingleIntId, args);
196
247
  case ID_TYPES.UUID:
197
- rules = rulesSingleUuidId;
198
- break;
248
+ return runSingleIdValidation(rulesSingleUuidId, args);
199
249
  case ID_TYPES.TEXT:
200
- rules = rulesSingleTextId;
201
- break;
250
+ return runSingleIdValidation(rulesSingleTextId, args);
251
+ default:
252
+ return [true, {}];
202
253
  }
203
- if (!rules) {
204
- return [true, {}];
205
- }
206
- const [result] = rules.validateSync(args);
207
- if (result) {
208
- return [createErrorOnCheckError(result)];
209
- }
210
- return [true, {}];
211
254
  };
255
+ /**
256
+ * Validates `args.where` for a remove() call using the core's configured idType.
257
+ * First checks that `where` is a non-empty object via `shouldHaveParams`,
258
+ * then applies the appropriate single-id rule set.
259
+ * Returns `[true, {}]` if idType is ID_TYPES.UNKNOWN or not set.
260
+ */
212
261
  export const validateRemove = async (args, opt) => {
213
262
  const { where } = args || {};
214
263
  const [idCheck] = shouldHaveParams(where);
@@ -216,52 +265,70 @@ export const validateRemove = async (args, opt) => {
216
265
  return [idCheck, {}];
217
266
  }
218
267
  const idType = opt.core.getIdType();
219
- let rules = null;
220
268
  switch (idType) {
221
269
  case ID_TYPES.INT:
222
- rules = rulesSingleIntId;
223
- break;
270
+ return runSingleIdValidation(rulesSingleIntId, where);
224
271
  case ID_TYPES.UUID:
225
- rules = rulesSingleUuidId;
226
- break;
272
+ return runSingleIdValidation(rulesSingleUuidId, where);
227
273
  case ID_TYPES.TEXT:
228
- rules = rulesSingleTextId;
229
- break;
230
- }
231
- if (!rules) {
232
- return [true, {}];
233
- }
234
- const [result] = rules.validateSync(where);
235
- if (result) {
236
- return [createErrorOnCheckError(result)];
274
+ return runSingleIdValidation(rulesSingleTextId, where);
275
+ default:
276
+ return [true, {}];
237
277
  }
238
- return [true, {}];
239
278
  };
279
+ /**
280
+ * Validates `args` for a getMany() call using the core's configured idType.
281
+ * Selects the appropriate multi-id rule set (int, UUID, or text).
282
+ * Returns `[true, {}]` immediately if idType is ID_TYPES.UNKNOWN or not set.
283
+ */
240
284
  export const validateGetMany = async (args, opt) => {
241
285
  const idType = opt.core.getIdType();
242
- let rules = null;
243
286
  switch (idType) {
244
287
  case ID_TYPES.INT:
245
- rules = rulesMultipleIntIds;
246
- break;
288
+ return runMultipleIdValidation(rulesMultipleIntIds, args);
247
289
  case ID_TYPES.UUID:
248
- rules = rulesMultipleUuidIds;
249
- break;
290
+ return runMultipleIdValidation(rulesMultipleUuidIds, args);
250
291
  case ID_TYPES.TEXT:
251
- rules = rulesMultipleTextIds;
252
- break;
292
+ return runMultipleIdValidation(rulesMultipleTextIds, args);
293
+ default:
294
+ return [true, {}];
253
295
  }
254
- if (!rules) {
255
- return [true, {}];
296
+ };
297
+ /**
298
+ * Validates `args.where` for a removeMany() call using the core's configured idType.
299
+ *
300
+ * Fix: removeMany() passes `args = { where: [...] }` to its validator, so we
301
+ * must validate `args.where` rather than `args` directly.
302
+ * Previously this was an alias of validateGetMany which validated `args.ids`
303
+ * directly — that worked only when idType was UNKNOWN (rules were skipped),
304
+ * but would fail silently for typed cores since `args.ids` would be undefined.
305
+ */
306
+ export const validateRemoveMany = async (args, opt) => {
307
+ const { where } = args || {};
308
+ const [idCheck] = shouldHaveParams(where);
309
+ if (idCheck !== true) {
310
+ return [idCheck, {}];
256
311
  }
257
- const [result] = rules.validateSync(args);
258
- if (result) {
259
- return [createErrorOnCheckError(result)];
312
+ const idType = opt.core.getIdType();
313
+ switch (idType) {
314
+ case ID_TYPES.INT:
315
+ return runMultipleIdValidation(rulesMultipleIntIds, where);
316
+ case ID_TYPES.UUID:
317
+ return runMultipleIdValidation(rulesMultipleUuidIds, where);
318
+ case ID_TYPES.TEXT:
319
+ return runMultipleIdValidation(rulesMultipleTextIds, where);
320
+ default:
321
+ return [true, {}];
260
322
  }
261
- return [true, {}];
262
323
  };
263
- export const validateRemoveMany = validateGetMany;
264
- export const validateCreate = ({ rules }) => async (args, opt) => {
324
+ /**
325
+ * Validates `args.params` for a create() call using caller-provided rules.
326
+ * First checks that `params` is a non-empty object, then applies the rules.
327
+ *
328
+ * Returns a factory function — call with `{ rules }` to get the validator:
329
+ * `validate: validateCreate({ rules: myCheckitRules })`
330
+ */
331
+ export const validateCreate = ({ rules }) => async (args, _opt) => {
265
332
  const { params } = args || {};
266
333
  const [paramsCheck] = shouldHaveParams(params);
267
334
  if (paramsCheck !== true) {
@@ -273,7 +340,16 @@ export const validateCreate = ({ rules }) => async (args, opt) => {
273
340
  }
274
341
  return [true, {}];
275
342
  };
276
- export const validateUpdate = ({ rules }) => async (args, opt) => {
343
+ /**
344
+ * Validates `args.where` and `args.params` for an update() call using
345
+ * caller-provided rules.
346
+ * Checks that both `where` and `params` are non-empty objects, then
347
+ * applies the rules to `params`.
348
+ *
349
+ * Returns a factory function — call with `{ rules }` to get the validator:
350
+ * `validate: validateUpdate({ rules: myCheckitRules })`
351
+ */
352
+ export const validateUpdate = ({ rules }) => async (args, _opt) => {
277
353
  const { where, params } = args || {};
278
354
  const [idCheck] = shouldHaveParams(where);
279
355
  if (idCheck !== true) {
@@ -289,7 +365,14 @@ export const validateUpdate = ({ rules }) => async (args, opt) => {
289
365
  }
290
366
  return [true, {}];
291
367
  };
292
- export const validateSet = ({ rules }) => async (args, opt) => {
368
+ /**
369
+ * Validates `args.params` for a set() (upsert) call using caller-provided rules.
370
+ * Checks that `params` is a non-empty object, then applies the rules.
371
+ *
372
+ * Returns a factory function — call with `{ rules }` to get the validator:
373
+ * `validate: validateSet({ rules: myCheckitRules })`
374
+ */
375
+ export const validateSet = ({ rules }) => async (args, _opt) => {
293
376
  const { params } = args || {};
294
377
  const [paramsCheck] = shouldHaveParams(params);
295
378
  if (paramsCheck !== true) {
@@ -301,3 +384,24 @@ export const validateSet = ({ rules }) => async (args, opt) => {
301
384
  }
302
385
  return [true, {}];
303
386
  };
387
+ // ─── Internal helpers ─────────────────────────────────────────────────────────
388
+ /**
389
+ * Runs a single-id Checkit rule set against the provided args and returns
390
+ * the standard `[errorOrTrue, {}]` validator tuple.
391
+ * Extracted to eliminate the repeated validateSync + createErrorOnCheckError
392
+ * pattern across validateGet and validateRemove.
393
+ */
394
+ const runSingleIdValidation = (rules, args) => {
395
+ const [result] = rules.validateSync(args);
396
+ return result ? [createErrorOnCheckError(result)] : [true, {}];
397
+ };
398
+ /**
399
+ * Runs a multi-id Checkit rule set against the provided args and returns
400
+ * the standard `[errorOrTrue, {}]` validator tuple.
401
+ * Extracted to eliminate the repeated validateSync + createErrorOnCheckError
402
+ * pattern across validateGetMany and validateRemoveMany.
403
+ */
404
+ const runMultipleIdValidation = (rules, args) => {
405
+ const [result] = rules.validateSync(args);
406
+ return result ? [createErrorOnCheckError(result)] : [true, {}];
407
+ };
@@ -0,0 +1,23 @@
1
+ import { BuildConfigOptions } from './interfaces';
2
+ /**
3
+ * Loads environment variables from a .env file and builds a typed config object.
4
+ *
5
+ * Reads the .env file at `dirName/.env` (or the path specified in `opt.envFile`),
6
+ * validates it against the example file at `dirName/.env.example` (or
7
+ * `opt.envFileExample`) using dotenv-safe, then converts all environment
8
+ * variables into a camelCase config object.
9
+ *
10
+ * Boolean coercion:
11
+ * Strings 'true' / '1' → true
12
+ * Strings 'false' / '0' → false
13
+ * (case-insensitive, handles common Docker/CI conventions)
14
+ *
15
+ * Always includes:
16
+ * - All env vars as camelCase keys with boolean coercion applied
17
+ * - `isProduction: boolean` — true when NODE_ENV === 'production'
18
+ *
19
+ * @param dirName Absolute path to the directory containing the .env files.
20
+ * Pass `__dirname` or `import.meta.dirname` from the entry point.
21
+ * @param opt Optional configuration overrides
22
+ */
23
+ export declare const buildConfig: (dirName: string, opt?: BuildConfigOptions) => Record<string, any>;
@@ -0,0 +1,69 @@
1
+ // ./src/configBuilder.ts
2
+ import { camelCase } from 'lodash';
3
+ import { resolve } from 'path';
4
+ import { config } from 'dotenv-safe';
5
+ /**
6
+ * Loads environment variables from a .env file and builds a typed config object.
7
+ *
8
+ * Reads the .env file at `dirName/.env` (or the path specified in `opt.envFile`),
9
+ * validates it against the example file at `dirName/.env.example` (or
10
+ * `opt.envFileExample`) using dotenv-safe, then converts all environment
11
+ * variables into a camelCase config object.
12
+ *
13
+ * Boolean coercion:
14
+ * Strings 'true' / '1' → true
15
+ * Strings 'false' / '0' → false
16
+ * (case-insensitive, handles common Docker/CI conventions)
17
+ *
18
+ * Always includes:
19
+ * - All env vars as camelCase keys with boolean coercion applied
20
+ * - `isProduction: boolean` — true when NODE_ENV === 'production'
21
+ *
22
+ * @param dirName Absolute path to the directory containing the .env files.
23
+ * Pass `__dirname` or `import.meta.dirname` from the entry point.
24
+ * @param opt Optional configuration overrides
25
+ */
26
+ export const buildConfig = (dirName, opt) => {
27
+ const opt2use = opt || {};
28
+ const envPath = resolve(dirName, opt2use.envFile || '.env');
29
+ const examplePath = resolve(dirName, opt2use.envFileExample || '.env.example');
30
+ // dotenv-safe throws MissingEnvVarsError if required vars from .env.example
31
+ // are absent, or ENOENT if the .env file itself does not exist.
32
+ // We catch and re-throw with a clearer message so startup failures are
33
+ // immediately actionable rather than showing a raw dotenv-safe stack trace.
34
+ try {
35
+ config({
36
+ path: envPath,
37
+ allowEmptyValues: opt2use.allowEmptyValues != null ? opt2use.allowEmptyValues : true,
38
+ example: examplePath,
39
+ });
40
+ }
41
+ catch (ex) {
42
+ throw new Error(`buildConfig failed to load environment variables.\n` +
43
+ ` env file: ${envPath}\n` +
44
+ ` example file: ${examplePath}\n` +
45
+ ` reason: ${ex?.message ?? String(ex)}`, { cause: ex });
46
+ }
47
+ // Merge process.env with a NODE_ENV default so the key is always present.
48
+ const env = Object.assign({ NODE_ENV: opt2use.defaultNodeEnv || 'development' }, process.env);
49
+ // Convert all env vars to camelCase keys with boolean coercion.
50
+ // camelCase('NODE_ENV') === 'nodeEnv', so nodeEnv is already included here.
51
+ const envVars = Object.keys(env).reduce((acc, key) => {
52
+ let value = env[key];
53
+ const tryValue = (value || '').toLowerCase();
54
+ // Coerce common boolean representations.
55
+ // Handles: 'true'/'false' (JS conventions) and '1'/'0' (Docker/CI conventions).
56
+ if (tryValue === 'false' || tryValue === '0') {
57
+ value = false;
58
+ }
59
+ else if (tryValue === 'true' || tryValue === '1') {
60
+ value = true;
61
+ }
62
+ acc[camelCase(key)] = value;
63
+ return acc;
64
+ }, {});
65
+ return {
66
+ ...envVars,
67
+ isProduction: env.NODE_ENV === 'production',
68
+ };
69
+ };