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