@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 +100 -0
- package/build/checkItHelpers.d.ts +81 -0
- package/build/checkItHelpers.js +174 -1
- package/build/commonValidators.d.ts +4 -2
- package/build/commonValidators.js +23 -11
- package/build/esm/checkItHelpers.d.ts +81 -0
- package/build/esm/checkItHelpers.js +167 -0
- package/build/esm/commonValidators.d.ts +4 -2
- package/build/esm/commonValidators.js +23 -11
- package/build/esm/index.d.ts +1 -0
- package/build/esm/index.js +1 -0
- package/build/esm/uuidHelpers.d.ts +26 -0
- package/build/esm/uuidHelpers.js +46 -0
- package/build/index.d.ts +1 -0
- package/build/index.js +1 -0
- package/build/uuidHelpers.d.ts +26 -0
- package/build/uuidHelpers.js +50 -0
- package/package.json +1 -3
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[];
|
package/build/checkItHelpers.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
*
|
|
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
|
-
{
|
|
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
|
|
79
|
-
*
|
|
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 (!
|
|
90
|
-
opResult.addError('ids', `The ids[${idx}] should be a UUID
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
*
|
|
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
|
-
{
|
|
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
|
|
73
|
-
*
|
|
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 (!
|
|
84
|
-
opResult.addError('ids', `The ids[${idx}] should be a UUID
|
|
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
|
|
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
|
|
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);
|
package/build/esm/index.d.ts
CHANGED
package/build/esm/index.js
CHANGED
|
@@ -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
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.
|
|
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",
|