@sdflc/backend-helpers 1.0.132 → 1.0.133

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? }` |
@@ -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);
@@ -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.133",
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",