@sdflc/backend-helpers 1.0.132 → 1.0.134

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,6 +50,9 @@ A comprehensive backend framework for Node.js applications providing database ac
50
50
  - [dbHelpers](#dbhelpers)
51
51
  - [Field helpers](#field-helpers)
52
52
  - [Validation helpers](#validation-helpers)
53
+ - [commonValidators](#commonvalidators)
54
+ - [UUID helpers](#uuid-helpers)
55
+ - [UUID rule factories](#uuid-rule-factories)
53
56
  - [Utility functions](#utility-functions)
54
57
  - [downloadFile](#downloadfile)
55
58
  - [passwordHelpers](#passwordhelpers)
@@ -1699,6 +1702,101 @@ export const validators = {
1699
1702
 
1700
1703
  ---
1701
1704
 
1705
+ ### UUID helpers
1706
+
1707
+ UUID validation primitives that work with any UUID variant — including MSSQL `newsequentialid()` output, whose version nibble falls outside the RFC 4122 `[1-5]` range that `is-uuid` and Checkit's built-in `uuid` rule enforce.
1708
+
1709
+ ```typescript
1710
+ import { isValidUuid, UUID_REGEX, UUID_NIL } from '@sdflc/backend-helpers';
1711
+
1712
+ isValidUuid('a1b2c3d4-e5f6-7890-abcd-ef1234567890'); // true (standard v4)
1713
+ isValidUuid('f1e2d3c4-b5a6-f789-abcd-ef1234567890'); // true (MSSQL newsequentialid)
1714
+ isValidUuid(UUID_NIL); // true (nil UUID is accepted as a sentinel)
1715
+ isValidUuid('not-a-uuid'); // false
1716
+ isValidUuid(null); // false
1717
+ ```
1718
+
1719
+ **Why structural validation?** The library validates format only — correct hyphen placement, segment lengths, and hex characters — and is lenient on the version/variant bits. This makes it safe to use with:
1720
+
1721
+ - Standard RFC 4122 v4 UUIDs (`crypto.randomUUID`, `uuidv4`, etc.)
1722
+ - MSSQL `newsequentialid()` sequential UUIDs
1723
+ - The nil UUID, commonly used as a system-owned sentinel (e.g. `createdBy = UUID_NIL` means "created by the system")
1724
+
1725
+ `UUID_NIL` is exported as a constant so call sites that do need to distinguish nil from real UUIDs can do so explicitly (`value === UUID_NIL`).
1726
+
1727
+ ---
1728
+
1729
+ ### UUID rule factories
1730
+
1731
+ Reusable Checkit rule definitions for validating UUID fields. Each factory is parameterised by field name, so the same building blocks cover any entity — `id`, `fileId`, `accountId`, `tagIds`, and so on — without writing custom rules per resource.
1732
+
1733
+ All factories use `isValidUuid` internally, so they accept the full range of UUIDs described above.
1734
+
1735
+ | Factory | Use for |
1736
+ | ------------------------------- | ----------------------------------------------------------------------------- |
1737
+ | `rulesRequiredUuid(field)` | Required scalar UUID (mandatory foreign keys — `partyId` on create) |
1738
+ | `rulesOptionalUuid(field)` | Optional scalar UUID (optional foreign keys) |
1739
+ | `rulesRequiredUuidArray(field)` | Required scalar-or-array of UUIDs, at least one present |
1740
+ | `rulesOptionalUuidArray(field)` | Optional scalar-or-array of UUIDs (filter fields like `{ tagIds: [...] }`) |
1741
+ | `rulesOptionalIntArray(field)` | Optional scalar-or-array of integers (companion rule for mixed filter shapes) |
1742
+
1743
+ Each factory returns a plain rule-definition object suitable for spreading into a Checkit rule set:
1744
+
1745
+ ```typescript
1746
+ import Checkit from 'checkit';
1747
+ import {
1748
+ rulesRequiredUuid,
1749
+ rulesOptionalUuid,
1750
+ rulesRequiredUuidArray,
1751
+ rulesOptionalUuidArray,
1752
+ rulesOptionalIntArray,
1753
+ } from '@sdflc/backend-helpers';
1754
+
1755
+ // Create rules — partyId is required, tagIds are optional
1756
+ const rulesCreate = new Checkit({
1757
+ ...rulesRequiredUuid('partyId'),
1758
+ ...rulesOptionalUuidArray('tagIds'),
1759
+ name: [{ rule: 'required', message: 'Name is required' }, { rule: 'string' }],
1760
+ });
1761
+
1762
+ // Filter rules — any combination may be present, but all must be valid UUIDs
1763
+ const rulesList = new Checkit({
1764
+ ...rulesOptionalUuidArray('partyId'),
1765
+ ...rulesOptionalUuidArray('personId'),
1766
+ ...rulesOptionalIntArray('rsvpStatus'),
1767
+ });
1768
+
1769
+ // Required multi-value field — scalar or array both accepted
1770
+ const rulesBulkAction = new Checkit({
1771
+ ...rulesRequiredUuidArray('fileIds'),
1772
+ });
1773
+ ```
1774
+
1775
+ **Input coercion:** the array factories use `lodash.castArray`, so a caller passing either `{ tagIds: 'uuid-1' }` or `{ tagIds: ['uuid-1', 'uuid-2'] }` is handled transparently — no need to pre-wrap scalars.
1776
+
1777
+ ---
1778
+
1779
+ ### filterValidUuids
1780
+
1781
+ A helper for sanitising input rather than rejecting it. Drops non-UUID entries from a list and logs each dropped value for diagnostics.
1782
+
1783
+ ```typescript
1784
+ import { filterValidUuids } from '@sdflc/backend-helpers';
1785
+
1786
+ // In a core method — sanitise a mixed list before a gateway call:
1787
+ const validIds = filterValidUuids(args.ids, 'noteCore.archive', this.logger);
1788
+
1789
+ if (validIds.length === 0) {
1790
+ return this.success([]);
1791
+ }
1792
+
1793
+ const records = await this.gateway.getMany(validIds);
1794
+ ```
1795
+
1796
+ Use this when skipping malformed entries is preferable to failing the whole operation — for example when enriching relations from a list that may contain stale or externally-sourced IDs. Use the rule factories instead when invalid input should cause a validation error.
1797
+
1798
+ ---
1799
+
1702
1800
  ## Migration and seeding utilities
1703
1801
 
1704
1802
  ### DbMigratorAndSeeder
@@ -1852,6 +1950,8 @@ ORDER_BYS.DESC; // 'desc'
1852
1950
  | `DataCachePropsInterface` | Full props for `DataCache` including request context |
1853
1951
  | `LoaderInterface` | Interface for custom loaders (`load`, `loadMany`, `clear`, `prime`) |
1854
1952
  | `GatewayFilterRule` | Single declarative filter rule: `{ field, column, type, columns? }` — used by `listFilters` / `updateFilters` / `removeFilters` / `countFilters` |
1953
+ | `UUID_REGEX` | Structural UUID regex constant — format validation only, no version/variant enforcement |
1954
+ | `UUID_NIL` | Nil UUID constant (`'00000000-0000-0000-0000-000000000000'`) — used as a system-owned sentinel |
1855
1955
  | `GatewayFilterType` | Union of filter strategy names: `'array' \| 'eq' \| 'bool' \| 'nullableBool' \| 'dateRange' \| 'nullableDateRange' \| 'search'` |
1856
1956
  | `SortItemInterface` | Single sort descriptor: `{ name: string, order: 'asc' \| 'desc' }` |
1857
1957
  | `RateLimitRule` | Rate-limit rule shape: `{ limit, windowSec, action? }` |
package/build/BaseCore.js CHANGED
@@ -743,7 +743,7 @@ class BaseCore {
743
743
  action: async (args, opt) => {
744
744
  const object = await this.beforeList(args, opt);
745
745
  if ((0, api_helpers_1.isOpResult)(object)) {
746
- return object;
746
+ return object.toJS();
747
747
  }
748
748
  const items = await this.getGateway()?.list(object);
749
749
  const result = await this.afterList(items, opt);
@@ -773,15 +773,20 @@ class BaseCore {
773
773
  action: async (args, opt) => {
774
774
  const args2use = await this.beforeGet(args, opt);
775
775
  if ((0, api_helpers_1.isOpResult)(args2use)) {
776
- return args2use;
776
+ return args2use.toJS();
777
777
  }
778
778
  if (args2use?.id == null) {
779
779
  return this.failure(api_helpers_1.OP_RESULT_CODES.NOT_FOUND, '', []);
780
780
  }
781
781
  const item = await this.getGateway()?.get(args2use.id);
782
+ if (this.getGateway()?.getConfig()?.hasRemovedAt === true) {
783
+ if (!item || item.removedAt) {
784
+ return this.failure(api_helpers_1.OP_RESULT_CODES.NOT_FOUND, `${this.config.name} not found`, []);
785
+ }
786
+ }
782
787
  const result = await this.afterGet(item, opt);
783
788
  if (!result) {
784
- return this.failure(api_helpers_1.OP_RESULT_CODES.NOT_FOUND, '', []);
789
+ return this.failure(api_helpers_1.OP_RESULT_CODES.NOT_FOUND, `${this.config.name} not found`, []);
785
790
  }
786
791
  return this.success([result]);
787
792
  },
@@ -809,12 +814,19 @@ class BaseCore {
809
814
  action: async (args, opt) => {
810
815
  const args2use = await this.beforeGetMany(args, opt);
811
816
  if ((0, api_helpers_1.isOpResult)(args2use)) {
812
- return args2use;
817
+ return args2use.toJS();
813
818
  }
814
819
  if (!Array.isArray(args2use?.ids)) {
815
820
  return this.failure(api_helpers_1.OP_RESULT_CODES.NOT_FOUND, 'Expected ids array but received invalid input', []);
816
821
  }
817
822
  const items = await this.getGateway()?.getMany(args2use.ids);
823
+ if (this.getGateway()?.getConfig()?.hasRemovedAt === true) {
824
+ items.forEach((item, index) => {
825
+ if (!item || item.removedAt) {
826
+ items[index] = null;
827
+ }
828
+ });
829
+ }
818
830
  const result = await this.afterGetMany(items, opt);
819
831
  return this.success(result);
820
832
  },
@@ -861,7 +873,7 @@ class BaseCore {
861
873
  }
862
874
  const object = await this.beforeCreate(params, opt);
863
875
  if ((0, api_helpers_1.isOpResult)(object)) {
864
- return object;
876
+ return object.toJS();
865
877
  }
866
878
  const items = await this.getGateway()?.create(object);
867
879
  const result = await this.afterCreate(items, opt);
@@ -889,7 +901,7 @@ class BaseCore {
889
901
  const { params } = args || {};
890
902
  const objects = await this.beforeCreateMany(params, opt);
891
903
  if ((0, api_helpers_1.isOpResult)(objects)) {
892
- return objects;
904
+ return objects.toJS();
893
905
  }
894
906
  const items = await this.getGateway()?.create(objects);
895
907
  const result = await this.afterCreateMany(items, opt);
@@ -920,7 +932,7 @@ class BaseCore {
920
932
  const { where, params } = args || {};
921
933
  const object = await this.beforeUpdate(params, opt);
922
934
  if ((0, api_helpers_1.isOpResult)(object)) {
923
- return object;
935
+ return object.toJS();
924
936
  }
925
937
  const items = await this.getGateway()?.update(where, object);
926
938
  const result = await this.afterUpdate(items, opt);
@@ -948,7 +960,7 @@ class BaseCore {
948
960
  const { params } = args || {};
949
961
  const object = await this.beforeUpdateMany(params, opt);
950
962
  if ((0, api_helpers_1.isOpResult)(object)) {
951
- return object;
963
+ return object.toJS();
952
964
  }
953
965
  const items = await this.getGateway()?.updateMany(object);
954
966
  const result = await this.afterUpdateMany(items, opt);
@@ -977,7 +989,7 @@ class BaseCore {
977
989
  const { params } = args || {};
978
990
  const object = await this.beforeSet(params, opt);
979
991
  if ((0, api_helpers_1.isOpResult)(object)) {
980
- return object;
992
+ return object.toJS();
981
993
  }
982
994
  const items = await this.getGateway()?.set(object);
983
995
  const result = await this.afterSet(items, opt);
@@ -1005,7 +1017,7 @@ class BaseCore {
1005
1017
  const { where } = args || {};
1006
1018
  const object = await this.beforeRemove(where, opt);
1007
1019
  if ((0, api_helpers_1.isOpResult)(object)) {
1008
- return object;
1020
+ return object.toJS();
1009
1021
  }
1010
1022
  const items = await this.getGateway()?.remove(object);
1011
1023
  const result = await this.afterRemove(items, opt);
@@ -1033,7 +1045,7 @@ class BaseCore {
1033
1045
  const { where } = args || {};
1034
1046
  const object = await this.beforeRemoveMany(where, opt);
1035
1047
  if ((0, api_helpers_1.isOpResult)(object)) {
1036
- return object;
1048
+ return object.toJS();
1037
1049
  }
1038
1050
  const items = await this.getGateway()?.remove(object);
1039
1051
  const result = await this.afterRemoveMany(items, opt);
@@ -1,4 +1,5 @@
1
1
  import { OpResult } from '@sdflc/api-helpers';
2
+ import { Logger } from '@sdflc/utils';
2
3
  /**
3
4
  * Validates each item in an array using a checkit-style validator and
4
5
  * accumulates all field errors into a single OpResult.
@@ -33,3 +34,83 @@ export declare const checkArray: (arr: any, validator: any, prefix?: string) =>
33
34
  * @param checkItResult A checkit validation error object
34
35
  */
35
36
  export declare const createErrorOnCheckError: (checkItResult: any) => OpResult;
37
+ /**
38
+ * Validates a single required UUID string for the given field.
39
+ * The value must be a scalar string (arrays are not accepted).
40
+ * Use for mandatory foreign-key fields (e.g. partyId on create).
41
+ */
42
+ export declare const rulesRequiredUuid: (field: string) => {
43
+ [x: string]: ({
44
+ rule: string;
45
+ message: string;
46
+ } | {
47
+ rule: (value: any) => void;
48
+ message?: undefined;
49
+ })[];
50
+ };
51
+ /**
52
+ * Validates a single optional UUID string for the given field.
53
+ * Absent values (null / undefined / empty string) pass silently.
54
+ * Present values must be structurally valid UUIDs.
55
+ * Use for optional foreign-key fields.
56
+ */
57
+ export declare const rulesOptionalUuid: (field: string) => {
58
+ [x: string]: {
59
+ rule: (value: any) => void;
60
+ }[];
61
+ };
62
+ /**
63
+ * Validates a required scalar-or-array of UUID strings for the given field.
64
+ * Accepts both a single UUID string and an array — a scalar is coerced via
65
+ * castArray so callers don't need to pre-wrap.
66
+ *
67
+ * At least one non-empty value must be present, and every present value
68
+ * must be a structurally valid UUID.
69
+ *
70
+ * Use for filter fields that accept "one or many" IDs (e.g. { fileId: uuid }
71
+ * or { fileId: [uuid1, uuid2] }).
72
+ */
73
+ export declare const rulesRequiredUuidArray: (field: string) => {
74
+ [x: string]: {
75
+ rule: (values: any) => void;
76
+ }[];
77
+ };
78
+ /**
79
+ * Validates an optional scalar-or-array of UUID strings for the given field.
80
+ * Absent values (null / undefined) pass silently.
81
+ * Present values are coerced via castArray; every element must be a
82
+ * structurally valid UUID.
83
+ *
84
+ * Use for optional multi-value filter fields (e.g. { tagIds: [...] }).
85
+ */
86
+ export declare const rulesOptionalUuidArray: (field: string) => {
87
+ [x: string]: {
88
+ rule: (value: any) => void;
89
+ }[];
90
+ };
91
+ /**
92
+ * Validates an optional scalar-or-array of integers for the given field.
93
+ * Absent values pass silently. Present values are coerced via castArray;
94
+ * every element must be an integer (Number-coercible and Number.isInteger).
95
+ *
96
+ * Use for optional multi-value numeric filter fields (e.g. { statusCodes: [...] }).
97
+ */
98
+ export declare const rulesOptionalIntArray: (field: string) => {
99
+ [x: string]: {
100
+ rule: (value: any) => void;
101
+ }[];
102
+ };
103
+ /**
104
+ * Filters a raw value (scalar or array) down to valid UUID strings only.
105
+ * Non-UUID entries are silently dropped and logged so they never reach a
106
+ * gateway as invalid bind parameters.
107
+ *
108
+ * Use when you need to *sanitize* input rather than *reject* it — for example
109
+ * when enriching relations from a mixed list where some IDs may be stale or
110
+ * malformed and skipping them is preferable to failing the whole operation.
111
+ *
112
+ * @param ids Raw value — a scalar, array, null, or undefined
113
+ * @param label Context label used in the skip log message
114
+ * @param logger Logger instance for reporting dropped values
115
+ */
116
+ export declare const filterValidUuids: (ids: any, label: string, logger: Logger) => string[];
@@ -1,8 +1,10 @@
1
1
  "use strict";
2
2
  // ./src/checkItHelpers.ts
3
3
  Object.defineProperty(exports, "__esModule", { value: true });
4
- exports.createErrorOnCheckError = exports.checkArray = void 0;
4
+ exports.filterValidUuids = exports.rulesOptionalIntArray = exports.rulesOptionalUuidArray = exports.rulesRequiredUuidArray = exports.rulesOptionalUuid = exports.rulesRequiredUuid = exports.createErrorOnCheckError = exports.checkArray = void 0;
5
+ const lodash_1 = require("lodash");
5
6
  const api_helpers_1 = require("@sdflc/api-helpers");
7
+ const uuidHelpers_1 = require("./uuidHelpers");
6
8
  /**
7
9
  * Validates each item in an array using a checkit-style validator and
8
10
  * accumulates all field errors into a single OpResult.
@@ -92,3 +94,174 @@ const createErrorOnCheckError = (checkItResult) => {
92
94
  return result;
93
95
  };
94
96
  exports.createErrorOnCheckError = createErrorOnCheckError;
97
+ // ─── UUID rule factories ──────────────────────────────────────────────────────
98
+ //
99
+ // Reusable Checkit rule definitions for validating UUID fields. All factories
100
+ // are parameterised by field name so they can be reused for any field
101
+ // (id, fileId, accountId, etc.) without needing to write custom rules per
102
+ // entity.
103
+ //
104
+ // All UUID validation uses `isValidUuid` from uuidHelpers, which accepts any
105
+ // structurally valid UUID including MSSQL newsequentialid() output and the
106
+ // nil UUID (the latter is commonly used as a system-owned sentinel).
107
+ //
108
+ // Each factory returns a plain rule-definition object suitable for spreading
109
+ // into a Checkit rule set, e.g.:
110
+ //
111
+ // const rules = new Checkit({
112
+ // ...rulesRequiredUuid('fileId'),
113
+ // ...rulesOptionalUuidArray('tagIds'),
114
+ // name: [{ rule: 'required' }],
115
+ // });
116
+ /**
117
+ * Validates a single required UUID string for the given field.
118
+ * The value must be a scalar string (arrays are not accepted).
119
+ * Use for mandatory foreign-key fields (e.g. partyId on create).
120
+ */
121
+ const rulesRequiredUuid = (field) => ({
122
+ [field]: [
123
+ {
124
+ rule: 'required',
125
+ message: `${field} is required`,
126
+ },
127
+ {
128
+ rule: (value) => {
129
+ if (!(0, uuidHelpers_1.isValidUuid)(value)) {
130
+ throw new Error(`${field} must be a valid UUID`);
131
+ }
132
+ },
133
+ },
134
+ ],
135
+ });
136
+ exports.rulesRequiredUuid = rulesRequiredUuid;
137
+ /**
138
+ * Validates a single optional UUID string for the given field.
139
+ * Absent values (null / undefined / empty string) pass silently.
140
+ * Present values must be structurally valid UUIDs.
141
+ * Use for optional foreign-key fields.
142
+ */
143
+ const rulesOptionalUuid = (field) => ({
144
+ [field]: [
145
+ {
146
+ rule: (value) => {
147
+ if (value == null || value === '')
148
+ return;
149
+ if (!(0, uuidHelpers_1.isValidUuid)(value)) {
150
+ throw new Error(`${field} must be a valid UUID`);
151
+ }
152
+ },
153
+ },
154
+ ],
155
+ });
156
+ exports.rulesOptionalUuid = rulesOptionalUuid;
157
+ /**
158
+ * Validates a required scalar-or-array of UUID strings for the given field.
159
+ * Accepts both a single UUID string and an array — a scalar is coerced via
160
+ * castArray so callers don't need to pre-wrap.
161
+ *
162
+ * At least one non-empty value must be present, and every present value
163
+ * must be a structurally valid UUID.
164
+ *
165
+ * Use for filter fields that accept "one or many" IDs (e.g. { fileId: uuid }
166
+ * or { fileId: [uuid1, uuid2] }).
167
+ */
168
+ const rulesRequiredUuidArray = (field) => ({
169
+ [field]: [
170
+ {
171
+ rule: (values) => {
172
+ const opResult = new api_helpers_1.OpResult();
173
+ const arr = (0, lodash_1.castArray)(values).filter((v) => v != null && v !== '');
174
+ if (arr.length === 0) {
175
+ opResult.addError(field, `At least one ${field} is required`);
176
+ opResult.setCode(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED);
177
+ throw opResult;
178
+ }
179
+ arr.forEach((value, idx) => {
180
+ if (!(0, uuidHelpers_1.isValidUuid)(value)) {
181
+ opResult.addError(field, `${field}[${idx}] must be a valid UUID`);
182
+ }
183
+ });
184
+ if (opResult.hasErrors()) {
185
+ opResult.setCode(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED);
186
+ throw opResult;
187
+ }
188
+ },
189
+ },
190
+ ],
191
+ });
192
+ exports.rulesRequiredUuidArray = rulesRequiredUuidArray;
193
+ /**
194
+ * Validates an optional scalar-or-array of UUID strings for the given field.
195
+ * Absent values (null / undefined) pass silently.
196
+ * Present values are coerced via castArray; every element must be a
197
+ * structurally valid UUID.
198
+ *
199
+ * Use for optional multi-value filter fields (e.g. { tagIds: [...] }).
200
+ */
201
+ const rulesOptionalUuidArray = (field) => ({
202
+ [field]: [
203
+ {
204
+ rule: (value) => {
205
+ if (value == null)
206
+ return;
207
+ (0, lodash_1.castArray)(value).forEach((v, idx) => {
208
+ if (!(0, uuidHelpers_1.isValidUuid)(v)) {
209
+ throw new Error(`${field}[${idx}] must be a valid UUID`);
210
+ }
211
+ });
212
+ },
213
+ },
214
+ ],
215
+ });
216
+ exports.rulesOptionalUuidArray = rulesOptionalUuidArray;
217
+ /**
218
+ * Validates an optional scalar-or-array of integers for the given field.
219
+ * Absent values pass silently. Present values are coerced via castArray;
220
+ * every element must be an integer (Number-coercible and Number.isInteger).
221
+ *
222
+ * Use for optional multi-value numeric filter fields (e.g. { statusCodes: [...] }).
223
+ */
224
+ const rulesOptionalIntArray = (field) => ({
225
+ [field]: [
226
+ {
227
+ rule: (value) => {
228
+ if (value == null)
229
+ return;
230
+ (0, lodash_1.castArray)(value).forEach((v, idx) => {
231
+ const n = Number(v);
232
+ if (isNaN(n) || !Number.isInteger(n)) {
233
+ throw new Error(`${field}[${idx}] must be an integer`);
234
+ }
235
+ });
236
+ },
237
+ },
238
+ ],
239
+ });
240
+ exports.rulesOptionalIntArray = rulesOptionalIntArray;
241
+ // ─── UUID list filter helper ──────────────────────────────────────────────────
242
+ /**
243
+ * Filters a raw value (scalar or array) down to valid UUID strings only.
244
+ * Non-UUID entries are silently dropped and logged so they never reach a
245
+ * gateway as invalid bind parameters.
246
+ *
247
+ * Use when you need to *sanitize* input rather than *reject* it — for example
248
+ * when enriching relations from a mixed list where some IDs may be stale or
249
+ * malformed and skipping them is preferable to failing the whole operation.
250
+ *
251
+ * @param ids Raw value — a scalar, array, null, or undefined
252
+ * @param label Context label used in the skip log message
253
+ * @param logger Logger instance for reporting dropped values
254
+ */
255
+ const filterValidUuids = (ids, label, logger) => {
256
+ const valid = [];
257
+ for (const id of (0, lodash_1.castArray)(ids)) {
258
+ if ((0, uuidHelpers_1.isValidUuid)(id)) {
259
+ valid.push(id);
260
+ }
261
+ else {
262
+ logger.log(`UUID filter (${label}) — skipping invalid value: "${id}"`);
263
+ }
264
+ }
265
+ return valid;
266
+ };
267
+ exports.filterValidUuids = filterValidUuids;
@@ -24,7 +24,8 @@ export declare const shouldHaveId: (id: any) => [OpResult | true];
24
24
  */
25
25
  export declare const validateSingleIntId: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
26
26
  /**
27
- * Validates that `args.id` is a present UUID v4.
27
+ * Validates that `args.id` is a present UUID.
28
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
28
29
  */
29
30
  export declare const validateSingleUuidId: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
30
31
  /**
@@ -36,7 +37,8 @@ export declare const validateSingleTextId: (args: any, _opt: BaseCoreActionsInte
36
37
  */
37
38
  export declare const validateMultipleIntIds: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
38
39
  /**
39
- * Validates that `args.ids` is a present array of UUID v4 values.
40
+ * Validates that `args.ids` is a present array of UUID values.
41
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
40
42
  */
41
43
  export declare const validateMultipleUuidIds: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
42
44
  /**
@@ -8,9 +8,9 @@ exports.validateSet = exports.validateUpdate = exports.validateCreate = exports.
8
8
  const lodash_1 = require("lodash");
9
9
  const checkit_1 = __importDefault(require("checkit"));
10
10
  const check_types_1 = __importDefault(require("check-types"));
11
- const is_uuid_1 = __importDefault(require("is-uuid"));
12
11
  const api_helpers_1 = require("@sdflc/api-helpers");
13
12
  const checkItHelpers_1 = require("./checkItHelpers");
13
+ const uuidHelpers_1 = require("./uuidHelpers");
14
14
  const constants_1 = require("./constants");
15
15
  // ─── Checkit rule sets ────────────────────────────────────────────────────────
16
16
  // Defined once at module level and reused across all validator calls.
@@ -26,15 +26,23 @@ const rulesSingleIntId = new checkit_1.default({
26
26
  ],
27
27
  });
28
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.
29
+ * Validates that `args.id` is present and is a valid UUID.
31
30
  *
32
- * Fix: error message was incorrectly saying 'ID should be an integer'.
31
+ * Uses `isValidUuid` (structural check) instead of Checkit's built-in `uuid`
32
+ * rule because the latter enforces RFC 4122 version/variant bits, which
33
+ * rejects MSSQL newsequentialid() UUIDs. The structural check accepts any
34
+ * UUID version including the nil UUID (used as a system-owned sentinel).
33
35
  */
34
36
  const rulesSingleUuidId = new checkit_1.default({
35
37
  id: [
36
38
  { rule: 'required', message: 'ID is required' },
37
- { rule: 'uuid', message: 'ID should be a UUID' },
39
+ {
40
+ rule: (value) => {
41
+ if (!(0, uuidHelpers_1.isValidUuid)(value)) {
42
+ throw new Error('ID should be a valid UUID');
43
+ }
44
+ },
45
+ },
38
46
  ],
39
47
  });
40
48
  /**
@@ -75,8 +83,10 @@ const rulesMultipleIntIds = new checkit_1.default({
75
83
  });
76
84
  /**
77
85
  * 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.
86
+ * is a valid UUID. The custom rule throws an OpResult on failure.
87
+ *
88
+ * Uses `isValidUuid` (structural check) rather than `is-uuid`'s v4 check so
89
+ * MSSQL newsequentialid() UUIDs and the nil UUID sentinel are accepted.
80
90
  */
81
91
  const rulesMultipleUuidIds = new checkit_1.default({
82
92
  ids: [
@@ -86,8 +96,8 @@ const rulesMultipleUuidIds = new checkit_1.default({
86
96
  rule: (values) => {
87
97
  const opResult = new api_helpers_1.OpResult();
88
98
  (0, lodash_1.castArray)(values).forEach((value, idx) => {
89
- if (!is_uuid_1.default.v4(value)) {
90
- opResult.addError('ids', `The ids[${idx}] should be a UUID of version 4`);
99
+ if (!(0, uuidHelpers_1.isValidUuid)(value)) {
100
+ opResult.addError('ids', `The ids[${idx}] should be a valid UUID`);
91
101
  }
92
102
  });
93
103
  if (opResult.hasErrors()) {
@@ -175,7 +185,8 @@ const validateSingleIntId = async (args, _opt) => {
175
185
  };
176
186
  exports.validateSingleIntId = validateSingleIntId;
177
187
  /**
178
- * Validates that `args.id` is a present UUID v4.
188
+ * Validates that `args.id` is a present UUID.
189
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
179
190
  */
180
191
  const validateSingleUuidId = async (args, _opt) => {
181
192
  const [result] = rulesSingleUuidId.validateSync(args);
@@ -208,7 +219,8 @@ const validateMultipleIntIds = async (args, _opt) => {
208
219
  };
209
220
  exports.validateMultipleIntIds = validateMultipleIntIds;
210
221
  /**
211
- * Validates that `args.ids` is a present array of UUID v4 values.
222
+ * Validates that `args.ids` is a present array of UUID values.
223
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
212
224
  */
213
225
  const validateMultipleUuidIds = async (args, _opt) => {
214
226
  const [result] = rulesMultipleUuidIds.validateSync(args);
@@ -737,7 +737,7 @@ class BaseCore {
737
737
  action: async (args, opt) => {
738
738
  const object = await this.beforeList(args, opt);
739
739
  if (isOpResult(object)) {
740
- return object;
740
+ return object.toJS();
741
741
  }
742
742
  const items = await this.getGateway()?.list(object);
743
743
  const result = await this.afterList(items, opt);
@@ -767,15 +767,20 @@ class BaseCore {
767
767
  action: async (args, opt) => {
768
768
  const args2use = await this.beforeGet(args, opt);
769
769
  if (isOpResult(args2use)) {
770
- return args2use;
770
+ return args2use.toJS();
771
771
  }
772
772
  if (args2use?.id == null) {
773
773
  return this.failure(OP_RESULT_CODES.NOT_FOUND, '', []);
774
774
  }
775
775
  const item = await this.getGateway()?.get(args2use.id);
776
+ if (this.getGateway()?.getConfig()?.hasRemovedAt === true) {
777
+ if (!item || item.removedAt) {
778
+ return this.failure(OP_RESULT_CODES.NOT_FOUND, `${this.config.name} not found`, []);
779
+ }
780
+ }
776
781
  const result = await this.afterGet(item, opt);
777
782
  if (!result) {
778
- return this.failure(OP_RESULT_CODES.NOT_FOUND, '', []);
783
+ return this.failure(OP_RESULT_CODES.NOT_FOUND, `${this.config.name} not found`, []);
779
784
  }
780
785
  return this.success([result]);
781
786
  },
@@ -803,12 +808,19 @@ class BaseCore {
803
808
  action: async (args, opt) => {
804
809
  const args2use = await this.beforeGetMany(args, opt);
805
810
  if (isOpResult(args2use)) {
806
- return args2use;
811
+ return args2use.toJS();
807
812
  }
808
813
  if (!Array.isArray(args2use?.ids)) {
809
814
  return this.failure(OP_RESULT_CODES.NOT_FOUND, 'Expected ids array but received invalid input', []);
810
815
  }
811
816
  const items = await this.getGateway()?.getMany(args2use.ids);
817
+ if (this.getGateway()?.getConfig()?.hasRemovedAt === true) {
818
+ items.forEach((item, index) => {
819
+ if (!item || item.removedAt) {
820
+ items[index] = null;
821
+ }
822
+ });
823
+ }
812
824
  const result = await this.afterGetMany(items, opt);
813
825
  return this.success(result);
814
826
  },
@@ -855,7 +867,7 @@ class BaseCore {
855
867
  }
856
868
  const object = await this.beforeCreate(params, opt);
857
869
  if (isOpResult(object)) {
858
- return object;
870
+ return object.toJS();
859
871
  }
860
872
  const items = await this.getGateway()?.create(object);
861
873
  const result = await this.afterCreate(items, opt);
@@ -883,7 +895,7 @@ class BaseCore {
883
895
  const { params } = args || {};
884
896
  const objects = await this.beforeCreateMany(params, opt);
885
897
  if (isOpResult(objects)) {
886
- return objects;
898
+ return objects.toJS();
887
899
  }
888
900
  const items = await this.getGateway()?.create(objects);
889
901
  const result = await this.afterCreateMany(items, opt);
@@ -914,7 +926,7 @@ class BaseCore {
914
926
  const { where, params } = args || {};
915
927
  const object = await this.beforeUpdate(params, opt);
916
928
  if (isOpResult(object)) {
917
- return object;
929
+ return object.toJS();
918
930
  }
919
931
  const items = await this.getGateway()?.update(where, object);
920
932
  const result = await this.afterUpdate(items, opt);
@@ -942,7 +954,7 @@ class BaseCore {
942
954
  const { params } = args || {};
943
955
  const object = await this.beforeUpdateMany(params, opt);
944
956
  if (isOpResult(object)) {
945
- return object;
957
+ return object.toJS();
946
958
  }
947
959
  const items = await this.getGateway()?.updateMany(object);
948
960
  const result = await this.afterUpdateMany(items, opt);
@@ -971,7 +983,7 @@ class BaseCore {
971
983
  const { params } = args || {};
972
984
  const object = await this.beforeSet(params, opt);
973
985
  if (isOpResult(object)) {
974
- return object;
986
+ return object.toJS();
975
987
  }
976
988
  const items = await this.getGateway()?.set(object);
977
989
  const result = await this.afterSet(items, opt);
@@ -999,7 +1011,7 @@ class BaseCore {
999
1011
  const { where } = args || {};
1000
1012
  const object = await this.beforeRemove(where, opt);
1001
1013
  if (isOpResult(object)) {
1002
- return object;
1014
+ return object.toJS();
1003
1015
  }
1004
1016
  const items = await this.getGateway()?.remove(object);
1005
1017
  const result = await this.afterRemove(items, opt);
@@ -1027,7 +1039,7 @@ class BaseCore {
1027
1039
  const { where } = args || {};
1028
1040
  const object = await this.beforeRemoveMany(where, opt);
1029
1041
  if (isOpResult(object)) {
1030
- return object;
1042
+ return object.toJS();
1031
1043
  }
1032
1044
  const items = await this.getGateway()?.remove(object);
1033
1045
  const result = await this.afterRemoveMany(items, opt);
@@ -1,4 +1,5 @@
1
1
  import { OpResult } from '@sdflc/api-helpers';
2
+ import { Logger } from '@sdflc/utils';
2
3
  /**
3
4
  * Validates each item in an array using a checkit-style validator and
4
5
  * accumulates all field errors into a single OpResult.
@@ -33,3 +34,83 @@ export declare const checkArray: (arr: any, validator: any, prefix?: string) =>
33
34
  * @param checkItResult A checkit validation error object
34
35
  */
35
36
  export declare const createErrorOnCheckError: (checkItResult: any) => OpResult;
37
+ /**
38
+ * Validates a single required UUID string for the given field.
39
+ * The value must be a scalar string (arrays are not accepted).
40
+ * Use for mandatory foreign-key fields (e.g. partyId on create).
41
+ */
42
+ export declare const rulesRequiredUuid: (field: string) => {
43
+ [x: string]: ({
44
+ rule: string;
45
+ message: string;
46
+ } | {
47
+ rule: (value: any) => void;
48
+ message?: undefined;
49
+ })[];
50
+ };
51
+ /**
52
+ * Validates a single optional UUID string for the given field.
53
+ * Absent values (null / undefined / empty string) pass silently.
54
+ * Present values must be structurally valid UUIDs.
55
+ * Use for optional foreign-key fields.
56
+ */
57
+ export declare const rulesOptionalUuid: (field: string) => {
58
+ [x: string]: {
59
+ rule: (value: any) => void;
60
+ }[];
61
+ };
62
+ /**
63
+ * Validates a required scalar-or-array of UUID strings for the given field.
64
+ * Accepts both a single UUID string and an array — a scalar is coerced via
65
+ * castArray so callers don't need to pre-wrap.
66
+ *
67
+ * At least one non-empty value must be present, and every present value
68
+ * must be a structurally valid UUID.
69
+ *
70
+ * Use for filter fields that accept "one or many" IDs (e.g. { fileId: uuid }
71
+ * or { fileId: [uuid1, uuid2] }).
72
+ */
73
+ export declare const rulesRequiredUuidArray: (field: string) => {
74
+ [x: string]: {
75
+ rule: (values: any) => void;
76
+ }[];
77
+ };
78
+ /**
79
+ * Validates an optional scalar-or-array of UUID strings for the given field.
80
+ * Absent values (null / undefined) pass silently.
81
+ * Present values are coerced via castArray; every element must be a
82
+ * structurally valid UUID.
83
+ *
84
+ * Use for optional multi-value filter fields (e.g. { tagIds: [...] }).
85
+ */
86
+ export declare const rulesOptionalUuidArray: (field: string) => {
87
+ [x: string]: {
88
+ rule: (value: any) => void;
89
+ }[];
90
+ };
91
+ /**
92
+ * Validates an optional scalar-or-array of integers for the given field.
93
+ * Absent values pass silently. Present values are coerced via castArray;
94
+ * every element must be an integer (Number-coercible and Number.isInteger).
95
+ *
96
+ * Use for optional multi-value numeric filter fields (e.g. { statusCodes: [...] }).
97
+ */
98
+ export declare const rulesOptionalIntArray: (field: string) => {
99
+ [x: string]: {
100
+ rule: (value: any) => void;
101
+ }[];
102
+ };
103
+ /**
104
+ * Filters a raw value (scalar or array) down to valid UUID strings only.
105
+ * Non-UUID entries are silently dropped and logged so they never reach a
106
+ * gateway as invalid bind parameters.
107
+ *
108
+ * Use when you need to *sanitize* input rather than *reject* it — for example
109
+ * when enriching relations from a mixed list where some IDs may be stale or
110
+ * malformed and skipping them is preferable to failing the whole operation.
111
+ *
112
+ * @param ids Raw value — a scalar, array, null, or undefined
113
+ * @param label Context label used in the skip log message
114
+ * @param logger Logger instance for reporting dropped values
115
+ */
116
+ export declare const filterValidUuids: (ids: any, label: string, logger: Logger) => string[];
@@ -1,5 +1,7 @@
1
1
  // ./src/checkItHelpers.ts
2
+ import { castArray } from 'lodash';
2
3
  import { OpResult, OP_RESULT_CODES } from '@sdflc/api-helpers';
4
+ import { isValidUuid } from './uuidHelpers';
3
5
  /**
4
6
  * Validates each item in an array using a checkit-style validator and
5
7
  * accumulates all field errors into a single OpResult.
@@ -87,3 +89,168 @@ export const createErrorOnCheckError = (checkItResult) => {
87
89
  });
88
90
  return result;
89
91
  };
92
+ // ─── UUID rule factories ──────────────────────────────────────────────────────
93
+ //
94
+ // Reusable Checkit rule definitions for validating UUID fields. All factories
95
+ // are parameterised by field name so they can be reused for any field
96
+ // (id, fileId, accountId, etc.) without needing to write custom rules per
97
+ // entity.
98
+ //
99
+ // All UUID validation uses `isValidUuid` from uuidHelpers, which accepts any
100
+ // structurally valid UUID including MSSQL newsequentialid() output and the
101
+ // nil UUID (the latter is commonly used as a system-owned sentinel).
102
+ //
103
+ // Each factory returns a plain rule-definition object suitable for spreading
104
+ // into a Checkit rule set, e.g.:
105
+ //
106
+ // const rules = new Checkit({
107
+ // ...rulesRequiredUuid('fileId'),
108
+ // ...rulesOptionalUuidArray('tagIds'),
109
+ // name: [{ rule: 'required' }],
110
+ // });
111
+ /**
112
+ * Validates a single required UUID string for the given field.
113
+ * The value must be a scalar string (arrays are not accepted).
114
+ * Use for mandatory foreign-key fields (e.g. partyId on create).
115
+ */
116
+ export const rulesRequiredUuid = (field) => ({
117
+ [field]: [
118
+ {
119
+ rule: 'required',
120
+ message: `${field} is required`,
121
+ },
122
+ {
123
+ rule: (value) => {
124
+ if (!isValidUuid(value)) {
125
+ throw new Error(`${field} must be a valid UUID`);
126
+ }
127
+ },
128
+ },
129
+ ],
130
+ });
131
+ /**
132
+ * Validates a single optional UUID string for the given field.
133
+ * Absent values (null / undefined / empty string) pass silently.
134
+ * Present values must be structurally valid UUIDs.
135
+ * Use for optional foreign-key fields.
136
+ */
137
+ export const rulesOptionalUuid = (field) => ({
138
+ [field]: [
139
+ {
140
+ rule: (value) => {
141
+ if (value == null || value === '')
142
+ return;
143
+ if (!isValidUuid(value)) {
144
+ throw new Error(`${field} must be a valid UUID`);
145
+ }
146
+ },
147
+ },
148
+ ],
149
+ });
150
+ /**
151
+ * Validates a required scalar-or-array of UUID strings for the given field.
152
+ * Accepts both a single UUID string and an array — a scalar is coerced via
153
+ * castArray so callers don't need to pre-wrap.
154
+ *
155
+ * At least one non-empty value must be present, and every present value
156
+ * must be a structurally valid UUID.
157
+ *
158
+ * Use for filter fields that accept "one or many" IDs (e.g. { fileId: uuid }
159
+ * or { fileId: [uuid1, uuid2] }).
160
+ */
161
+ export const rulesRequiredUuidArray = (field) => ({
162
+ [field]: [
163
+ {
164
+ rule: (values) => {
165
+ const opResult = new OpResult();
166
+ const arr = castArray(values).filter((v) => v != null && v !== '');
167
+ if (arr.length === 0) {
168
+ opResult.addError(field, `At least one ${field} is required`);
169
+ opResult.setCode(OP_RESULT_CODES.VALIDATION_FAILED);
170
+ throw opResult;
171
+ }
172
+ arr.forEach((value, idx) => {
173
+ if (!isValidUuid(value)) {
174
+ opResult.addError(field, `${field}[${idx}] must be a valid UUID`);
175
+ }
176
+ });
177
+ if (opResult.hasErrors()) {
178
+ opResult.setCode(OP_RESULT_CODES.VALIDATION_FAILED);
179
+ throw opResult;
180
+ }
181
+ },
182
+ },
183
+ ],
184
+ });
185
+ /**
186
+ * Validates an optional scalar-or-array of UUID strings for the given field.
187
+ * Absent values (null / undefined) pass silently.
188
+ * Present values are coerced via castArray; every element must be a
189
+ * structurally valid UUID.
190
+ *
191
+ * Use for optional multi-value filter fields (e.g. { tagIds: [...] }).
192
+ */
193
+ export const rulesOptionalUuidArray = (field) => ({
194
+ [field]: [
195
+ {
196
+ rule: (value) => {
197
+ if (value == null)
198
+ return;
199
+ castArray(value).forEach((v, idx) => {
200
+ if (!isValidUuid(v)) {
201
+ throw new Error(`${field}[${idx}] must be a valid UUID`);
202
+ }
203
+ });
204
+ },
205
+ },
206
+ ],
207
+ });
208
+ /**
209
+ * Validates an optional scalar-or-array of integers for the given field.
210
+ * Absent values pass silently. Present values are coerced via castArray;
211
+ * every element must be an integer (Number-coercible and Number.isInteger).
212
+ *
213
+ * Use for optional multi-value numeric filter fields (e.g. { statusCodes: [...] }).
214
+ */
215
+ export const rulesOptionalIntArray = (field) => ({
216
+ [field]: [
217
+ {
218
+ rule: (value) => {
219
+ if (value == null)
220
+ return;
221
+ castArray(value).forEach((v, idx) => {
222
+ const n = Number(v);
223
+ if (isNaN(n) || !Number.isInteger(n)) {
224
+ throw new Error(`${field}[${idx}] must be an integer`);
225
+ }
226
+ });
227
+ },
228
+ },
229
+ ],
230
+ });
231
+ // ─── UUID list filter helper ──────────────────────────────────────────────────
232
+ /**
233
+ * Filters a raw value (scalar or array) down to valid UUID strings only.
234
+ * Non-UUID entries are silently dropped and logged so they never reach a
235
+ * gateway as invalid bind parameters.
236
+ *
237
+ * Use when you need to *sanitize* input rather than *reject* it — for example
238
+ * when enriching relations from a mixed list where some IDs may be stale or
239
+ * malformed and skipping them is preferable to failing the whole operation.
240
+ *
241
+ * @param ids Raw value — a scalar, array, null, or undefined
242
+ * @param label Context label used in the skip log message
243
+ * @param logger Logger instance for reporting dropped values
244
+ */
245
+ export const filterValidUuids = (ids, label, logger) => {
246
+ const valid = [];
247
+ for (const id of castArray(ids)) {
248
+ if (isValidUuid(id)) {
249
+ valid.push(id);
250
+ }
251
+ else {
252
+ logger.log(`UUID filter (${label}) — skipping invalid value: "${id}"`);
253
+ }
254
+ }
255
+ return valid;
256
+ };
@@ -24,7 +24,8 @@ export declare const shouldHaveId: (id: any) => [OpResult | true];
24
24
  */
25
25
  export declare const validateSingleIntId: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
26
26
  /**
27
- * Validates that `args.id` is a present UUID v4.
27
+ * Validates that `args.id` is a present UUID.
28
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
28
29
  */
29
30
  export declare const validateSingleUuidId: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
30
31
  /**
@@ -36,7 +37,8 @@ export declare const validateSingleTextId: (args: any, _opt: BaseCoreActionsInte
36
37
  */
37
38
  export declare const validateMultipleIntIds: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
38
39
  /**
39
- * Validates that `args.ids` is a present array of UUID v4 values.
40
+ * Validates that `args.ids` is a present array of UUID values.
41
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
40
42
  */
41
43
  export declare const validateMultipleUuidIds: (args: any, _opt: BaseCoreActionsInterface) => Promise<any[]>;
42
44
  /**
@@ -2,9 +2,9 @@
2
2
  import { castArray } from 'lodash';
3
3
  import Checkit from 'checkit';
4
4
  import check from 'check-types';
5
- import isUUID from 'is-uuid';
6
5
  import { OpResult, OP_RESULT_CODES } from '@sdflc/api-helpers';
7
6
  import { createErrorOnCheckError } from './checkItHelpers';
7
+ import { isValidUuid } from './uuidHelpers';
8
8
  import { ID_TYPES } from './constants';
9
9
  // ─── Checkit rule sets ────────────────────────────────────────────────────────
10
10
  // Defined once at module level and reused across all validator calls.
@@ -20,15 +20,23 @@ const rulesSingleIntId = new Checkit({
20
20
  ],
21
21
  });
22
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.
23
+ * Validates that `args.id` is present and is a valid UUID.
25
24
  *
26
- * Fix: error message was incorrectly saying 'ID should be an integer'.
25
+ * Uses `isValidUuid` (structural check) instead of Checkit's built-in `uuid`
26
+ * rule because the latter enforces RFC 4122 version/variant bits, which
27
+ * rejects MSSQL newsequentialid() UUIDs. The structural check accepts any
28
+ * UUID version including the nil UUID (used as a system-owned sentinel).
27
29
  */
28
30
  const rulesSingleUuidId = new Checkit({
29
31
  id: [
30
32
  { rule: 'required', message: 'ID is required' },
31
- { rule: 'uuid', message: 'ID should be a UUID' },
33
+ {
34
+ rule: (value) => {
35
+ if (!isValidUuid(value)) {
36
+ throw new Error('ID should be a valid UUID');
37
+ }
38
+ },
39
+ },
32
40
  ],
33
41
  });
34
42
  /**
@@ -69,8 +77,10 @@ const rulesMultipleIntIds = new Checkit({
69
77
  });
70
78
  /**
71
79
  * 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.
80
+ * is a valid UUID. The custom rule throws an OpResult on failure.
81
+ *
82
+ * Uses `isValidUuid` (structural check) rather than `is-uuid`'s v4 check so
83
+ * MSSQL newsequentialid() UUIDs and the nil UUID sentinel are accepted.
74
84
  */
75
85
  const rulesMultipleUuidIds = new Checkit({
76
86
  ids: [
@@ -80,8 +90,8 @@ const rulesMultipleUuidIds = new Checkit({
80
90
  rule: (values) => {
81
91
  const opResult = new OpResult();
82
92
  castArray(values).forEach((value, idx) => {
83
- if (!isUUID.v4(value)) {
84
- opResult.addError('ids', `The ids[${idx}] should be a UUID of version 4`);
93
+ if (!isValidUuid(value)) {
94
+ opResult.addError('ids', `The ids[${idx}] should be a valid UUID`);
85
95
  }
86
96
  });
87
97
  if (opResult.hasErrors()) {
@@ -166,7 +176,8 @@ export const validateSingleIntId = async (args, _opt) => {
166
176
  return [true, {}];
167
177
  };
168
178
  /**
169
- * Validates that `args.id` is a present UUID v4.
179
+ * Validates that `args.id` is a present UUID.
180
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
170
181
  */
171
182
  export const validateSingleUuidId = async (args, _opt) => {
172
183
  const [result] = rulesSingleUuidId.validateSync(args);
@@ -196,7 +207,8 @@ export const validateMultipleIntIds = async (args, _opt) => {
196
207
  return [true, {}];
197
208
  };
198
209
  /**
199
- * Validates that `args.ids` is a present array of UUID v4 values.
210
+ * Validates that `args.ids` is a present array of UUID values.
211
+ * Accepts any structurally valid UUID including MSSQL newsequentialid() output.
200
212
  */
201
213
  export const validateMultipleUuidIds = async (args, _opt) => {
202
214
  const [result] = rulesMultipleUuidIds.validateSync(args);
@@ -23,3 +23,4 @@ export * from './resolveClientIp';
23
23
  export * from './BaseRestApiCrudController';
24
24
  export * from './BaseExternalApiGateway';
25
25
  export * from './IpRateLimiter';
26
+ export * from './uuidHelpers';
@@ -23,3 +23,4 @@ export * from './resolveClientIp';
23
23
  export * from './BaseRestApiCrudController';
24
24
  export * from './BaseExternalApiGateway';
25
25
  export * from './IpRateLimiter';
26
+ export * from './uuidHelpers';
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Structural UUID regex — validates format only, not RFC 4122 version/variant bits.
3
+ */
4
+ export declare const UUID_REGEX: RegExp;
5
+ /**
6
+ * The nil UUID — all zeros. Commonly used as a sentinel for system-owned
7
+ * references (e.g. createdBy = UUID_NIL indicates the record was created
8
+ * by the system rather than by a user).
9
+ */
10
+ export declare const UUID_NIL = "00000000-0000-0000-0000-000000000000";
11
+ /**
12
+ * Returns true when the value is a structurally valid UUID string.
13
+ *
14
+ * Accepts:
15
+ * - Any UUID version (1-5, plus non-standard versions like MSSQL's "f")
16
+ * - Nil UUID (all zeros), which is commonly used as a system-owned sentinel
17
+ *
18
+ * Rejects:
19
+ * - Non-string values
20
+ * - Strings that don't match the structural format (wrong length, bad chars,
21
+ * missing/misplaced hyphens)
22
+ *
23
+ * Use this in place of `is-uuid` or Checkit's `uuid` rule when working with
24
+ * MSSQL-generated UUIDs or any database that uses non-RFC-4122 UUID generation.
25
+ */
26
+ export declare const isValidUuid: (value: unknown) => value is string;
@@ -0,0 +1,46 @@
1
+ // ./src/uuidHelpers.ts
2
+ // ─── UUID validation primitives ───────────────────────────────────────────────
3
+ //
4
+ // The `is-uuid` library and Checkit's built-in `uuid` rule both validate the
5
+ // UUID version/variant nibbles per RFC 4122 — rejecting anything whose version
6
+ // nibble is outside [1-5]. Microsoft SQL Server's newsequentialid() generates
7
+ // sequential UUIDs with version nibbles outside this range (e.g. "f111"),
8
+ // causing every MSSQL-generated ID to be rejected.
9
+ //
10
+ // We therefore use a plain structural regex that validates UUID format only:
11
+ // - Correct hyphen placement and segment lengths
12
+ // - Hex characters only
13
+ // - Nil UUID is accepted — it's commonly used as a sentinel for system-owned
14
+ // references (e.g. createdBy = nil UUID means "created by the system")
15
+ //
16
+ // This is intentionally lenient on version/variant bits so it works with:
17
+ // - Standard RFC 4122 v4 UUIDs (crypto.randomUUID, uuidv4, etc.)
18
+ // - MSSQL newsequentialid() UUIDs (version nibble outside [1-5])
19
+ // - Nil UUID used as a system-owned sentinel
20
+ // - Any other UUID variant generated by the database or external systems
21
+ /**
22
+ * Structural UUID regex — validates format only, not RFC 4122 version/variant bits.
23
+ */
24
+ export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
25
+ /**
26
+ * The nil UUID — all zeros. Commonly used as a sentinel for system-owned
27
+ * references (e.g. createdBy = UUID_NIL indicates the record was created
28
+ * by the system rather than by a user).
29
+ */
30
+ export const UUID_NIL = '00000000-0000-0000-0000-000000000000';
31
+ /**
32
+ * Returns true when the value is a structurally valid UUID string.
33
+ *
34
+ * Accepts:
35
+ * - Any UUID version (1-5, plus non-standard versions like MSSQL's "f")
36
+ * - Nil UUID (all zeros), which is commonly used as a system-owned sentinel
37
+ *
38
+ * Rejects:
39
+ * - Non-string values
40
+ * - Strings that don't match the structural format (wrong length, bad chars,
41
+ * missing/misplaced hyphens)
42
+ *
43
+ * Use this in place of `is-uuid` or Checkit's `uuid` rule when working with
44
+ * MSSQL-generated UUIDs or any database that uses non-RFC-4122 UUID generation.
45
+ */
46
+ export const isValidUuid = (value) => typeof value === 'string' && UUID_REGEX.test(value);
package/build/index.d.ts CHANGED
@@ -23,3 +23,4 @@ export * from './resolveClientIp';
23
23
  export * from './BaseRestApiCrudController';
24
24
  export * from './BaseExternalApiGateway';
25
25
  export * from './IpRateLimiter';
26
+ export * from './uuidHelpers';
package/build/index.js CHANGED
@@ -39,3 +39,4 @@ __exportStar(require("./resolveClientIp"), exports);
39
39
  __exportStar(require("./BaseRestApiCrudController"), exports);
40
40
  __exportStar(require("./BaseExternalApiGateway"), exports);
41
41
  __exportStar(require("./IpRateLimiter"), exports);
42
+ __exportStar(require("./uuidHelpers"), exports);
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Structural UUID regex — validates format only, not RFC 4122 version/variant bits.
3
+ */
4
+ export declare const UUID_REGEX: RegExp;
5
+ /**
6
+ * The nil UUID — all zeros. Commonly used as a sentinel for system-owned
7
+ * references (e.g. createdBy = UUID_NIL indicates the record was created
8
+ * by the system rather than by a user).
9
+ */
10
+ export declare const UUID_NIL = "00000000-0000-0000-0000-000000000000";
11
+ /**
12
+ * Returns true when the value is a structurally valid UUID string.
13
+ *
14
+ * Accepts:
15
+ * - Any UUID version (1-5, plus non-standard versions like MSSQL's "f")
16
+ * - Nil UUID (all zeros), which is commonly used as a system-owned sentinel
17
+ *
18
+ * Rejects:
19
+ * - Non-string values
20
+ * - Strings that don't match the structural format (wrong length, bad chars,
21
+ * missing/misplaced hyphens)
22
+ *
23
+ * Use this in place of `is-uuid` or Checkit's `uuid` rule when working with
24
+ * MSSQL-generated UUIDs or any database that uses non-RFC-4122 UUID generation.
25
+ */
26
+ export declare const isValidUuid: (value: unknown) => value is string;
@@ -0,0 +1,50 @@
1
+ "use strict";
2
+ // ./src/uuidHelpers.ts
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.isValidUuid = exports.UUID_NIL = exports.UUID_REGEX = void 0;
5
+ // ─── UUID validation primitives ───────────────────────────────────────────────
6
+ //
7
+ // The `is-uuid` library and Checkit's built-in `uuid` rule both validate the
8
+ // UUID version/variant nibbles per RFC 4122 — rejecting anything whose version
9
+ // nibble is outside [1-5]. Microsoft SQL Server's newsequentialid() generates
10
+ // sequential UUIDs with version nibbles outside this range (e.g. "f111"),
11
+ // causing every MSSQL-generated ID to be rejected.
12
+ //
13
+ // We therefore use a plain structural regex that validates UUID format only:
14
+ // - Correct hyphen placement and segment lengths
15
+ // - Hex characters only
16
+ // - Nil UUID is accepted — it's commonly used as a sentinel for system-owned
17
+ // references (e.g. createdBy = nil UUID means "created by the system")
18
+ //
19
+ // This is intentionally lenient on version/variant bits so it works with:
20
+ // - Standard RFC 4122 v4 UUIDs (crypto.randomUUID, uuidv4, etc.)
21
+ // - MSSQL newsequentialid() UUIDs (version nibble outside [1-5])
22
+ // - Nil UUID used as a system-owned sentinel
23
+ // - Any other UUID variant generated by the database or external systems
24
+ /**
25
+ * Structural UUID regex — validates format only, not RFC 4122 version/variant bits.
26
+ */
27
+ exports.UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
28
+ /**
29
+ * The nil UUID — all zeros. Commonly used as a sentinel for system-owned
30
+ * references (e.g. createdBy = UUID_NIL indicates the record was created
31
+ * by the system rather than by a user).
32
+ */
33
+ exports.UUID_NIL = '00000000-0000-0000-0000-000000000000';
34
+ /**
35
+ * Returns true when the value is a structurally valid UUID string.
36
+ *
37
+ * Accepts:
38
+ * - Any UUID version (1-5, plus non-standard versions like MSSQL's "f")
39
+ * - Nil UUID (all zeros), which is commonly used as a system-owned sentinel
40
+ *
41
+ * Rejects:
42
+ * - Non-string values
43
+ * - Strings that don't match the structural format (wrong length, bad chars,
44
+ * missing/misplaced hyphens)
45
+ *
46
+ * Use this in place of `is-uuid` or Checkit's `uuid` rule when working with
47
+ * MSSQL-generated UUIDs or any database that uses non-RFC-4122 UUID generation.
48
+ */
49
+ const isValidUuid = (value) => typeof value === 'string' && exports.UUID_REGEX.test(value);
50
+ exports.isValidUuid = isValidUuid;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.132",
3
+ "version": "1.0.134",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {
@@ -36,7 +36,6 @@
36
36
  "@types/bluebird": "^3.5.42",
37
37
  "@types/check-types": "^11.2.2",
38
38
  "@types/dotenv-safe": "^9.1.0",
39
- "@types/is-uuid": "^1.0.2",
40
39
  "@types/jest": "^30.0.0",
41
40
  "@types/jsonwebtoken": "^9.0.10",
42
41
  "@types/lodash": "^4.17.24",
@@ -67,7 +66,6 @@
67
66
  "dataloader": "^2.2.3",
68
67
  "dayjs": "^1.11.20",
69
68
  "dotenv-safe": "^9.1.0",
70
- "is-uuid": "^1.0.2",
71
69
  "json-stable-stringify": "^1.3.0",
72
70
  "jsonwebtoken": "^9.0.3",
73
71
  "knex": "^3.2.6",