is-kit 1.16.4 → 1.16.6
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 +46 -3
- package/bin/is-kit.mjs +28 -8
- package/dist/index.d.mts +6 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +22 -7
- package/dist/index.mjs +22 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -112,6 +112,18 @@ ship the legacy JavaScript Compiler API. Tools that need that API can follow
|
|
|
112
112
|
the official [TypeScript 7 side-by-side guidance](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6-0)
|
|
113
113
|
and use `@typescript/typescript6` for programmatic access.
|
|
114
114
|
|
|
115
|
+
### Runtime compatibility
|
|
116
|
+
|
|
117
|
+
- **Node.js 22 or newer** is the supported runtime baseline, matching the
|
|
118
|
+
`engines` field in `package.json`.
|
|
119
|
+
- The published TypeScript declarations support **TypeScript 5.4 and newer**.
|
|
120
|
+
- Both **ESM and CommonJS** builds are published, so `import` and `require`
|
|
121
|
+
consumers are equally supported.
|
|
122
|
+
|
|
123
|
+
`is-kit` may appear to run on an older Node.js version, but successful
|
|
124
|
+
execution there does not imply official support: only the baseline above is
|
|
125
|
+
covered by the project's compatibility guarantees and CI.
|
|
126
|
+
|
|
115
127
|
vlt requires registry configuration before installing a package by name. Run
|
|
116
128
|
`vlt setup` once if a registry has not been configured yet.
|
|
117
129
|
|
|
@@ -384,7 +396,37 @@ const isConfig = struct({
|
|
|
384
396
|
});
|
|
385
397
|
```
|
|
386
398
|
|
|
387
|
-
`
|
|
399
|
+
`optional(guard)` and `optionalKey(guard)` answer different questions.
|
|
400
|
+
`optional` is about the value: the key must be there, but it may hold
|
|
401
|
+
`undefined`. `optionalKey` is about the key: it may be missing, but when it is
|
|
402
|
+
there the value must pass the guard. Here is how each one treats `tag` in
|
|
403
|
+
`struct({ id: isNumber, tag: ... })`:
|
|
404
|
+
|
|
405
|
+
| Field schema | `{ id: 1, tag: 'hello' }` | `{ id: 1, tag: undefined }` | `{ id: 1 }` | Inferred `tag` |
|
|
406
|
+
| -------------------------------------- | ------------------------- | --------------------------- | ----------- | --------------------------- |
|
|
407
|
+
| `tag: optional(isString)` | ✅ | ✅ | ❌ | `tag: string \| undefined` |
|
|
408
|
+
| `tag: optionalKey(isString)` | ✅ | ❌ | ✅ | `tag?: string` |
|
|
409
|
+
| `tag: optionalKey(optional(isString))` | ✅ | ✅ | ✅ | `tag?: string \| undefined` |
|
|
410
|
+
|
|
411
|
+
If you come from a schema library where `.optional()` accepts both a missing
|
|
412
|
+
key and `undefined`, the match is `optionalKey(optional(guard))`.
|
|
413
|
+
|
|
414
|
+
The difference shows up with API and JSON payloads. Building an object from a
|
|
415
|
+
maybe-undefined variable keeps the key, and `JSON.stringify` drops it:
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
const tag: string | undefined = undefined;
|
|
419
|
+
const payload = { id: 1, tag }; // { id: 1, tag: undefined }, the key is present
|
|
420
|
+
|
|
421
|
+
struct({ id: isNumber, tag: optionalKey(isString) })(payload); // false
|
|
422
|
+
|
|
423
|
+
const received = JSON.parse(JSON.stringify(payload)); // { id: 1 }, the key is gone
|
|
424
|
+
struct({ id: isNumber, tag: optional(isString) })(received); // false
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
So a guard that checks objects you build in code and the same objects after a
|
|
428
|
+
JSON round trip needs `optionalKey(optional(guard))` for fields that may be
|
|
429
|
+
`undefined`.
|
|
388
430
|
|
|
389
431
|
Use `struct(schema, { exact: true })` when extra own enumerable string keys
|
|
390
432
|
should be rejected. Exact mode follows `Object.keys(...)` semantics, so symbol
|
|
@@ -394,8 +436,6 @@ Schemas themselves must use own enumerable string keys. `struct` rejects
|
|
|
394
436
|
symbol-keyed, non-enumerable, and inherited schema fields so its runtime checks
|
|
395
437
|
match the inferred type.
|
|
396
438
|
|
|
397
|
-
If the property must exist but the value may be `undefined`, use `optional(guard)` instead.
|
|
398
|
-
|
|
399
439
|
### 5. Validate arrays, tuples, maps, sets, and records
|
|
400
440
|
|
|
401
441
|
Collection combinators keep your element guards reusable.
|
|
@@ -838,6 +878,9 @@ public root exports are planned for removal.
|
|
|
838
878
|
For detailed API pages and more examples, see:
|
|
839
879
|
|
|
840
880
|
- [Practical guides](https://is-kit.dev/guides)
|
|
881
|
+
- [Design principles and non-goals](https://is-kit.dev/guides/design-principles)
|
|
882
|
+
- [Best practices for real projects](https://is-kit.dev/guides/best-practices)
|
|
883
|
+
- [Where to validate in a real application](https://is-kit.dev/guides/where-to-validate)
|
|
841
884
|
- [Keep hand-written type guards in sync with TypeScript types](https://is-kit.dev/guides/keep-type-guards-in-sync)
|
|
842
885
|
- [Refine properties on existing TypeScript types](https://is-kit.dev/guides/refine-properties-on-existing-types)
|
|
843
886
|
- [Advanced property refinement with the TypeScript Compiler API](https://is-kit.dev/guides/typescript-compiler-api)
|
package/bin/is-kit.mjs
CHANGED
|
@@ -27,19 +27,39 @@ const fileExists = async (path) => {
|
|
|
27
27
|
}
|
|
28
28
|
};
|
|
29
29
|
|
|
30
|
-
const
|
|
31
|
-
|
|
30
|
+
const validateTargetValue = (value) => {
|
|
31
|
+
if (value === undefined || value.length === 0) {
|
|
32
|
+
throw new Error('Missing value for --target');
|
|
33
|
+
}
|
|
32
34
|
|
|
33
|
-
if (
|
|
34
|
-
|
|
35
|
+
if (!Object.hasOwn(TARGET_FILES, value)) {
|
|
36
|
+
throw new Error(`Unknown target: ${value}`);
|
|
35
37
|
}
|
|
36
38
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
39
|
+
return value;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
const parseTarget = (args) => {
|
|
43
|
+
let target;
|
|
44
|
+
|
|
45
|
+
for (let index = 0; index < args.length; index += 1) {
|
|
46
|
+
const arg = args[index];
|
|
47
|
+
|
|
48
|
+
if (arg === '--target' || arg.startsWith('--target=')) {
|
|
49
|
+
if (target !== undefined) {
|
|
50
|
+
throw new Error('Repeated --target option');
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const isInline = arg.startsWith('--target=');
|
|
54
|
+
const value = isInline ? arg.slice('--target='.length) : args[++index];
|
|
55
|
+
target = validateTargetValue(value);
|
|
56
|
+
continue;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
throw new Error(`Unknown option: ${arg}`);
|
|
40
60
|
}
|
|
41
61
|
|
|
42
|
-
return target;
|
|
62
|
+
return target ?? 'agents';
|
|
43
63
|
};
|
|
44
64
|
|
|
45
65
|
const updateManagedSection = (existingContent, rules) => {
|
package/dist/index.d.mts
CHANGED
|
@@ -885,6 +885,12 @@ export declare function typedStruct<T extends object>(): <const S extends TypedS
|
|
|
885
885
|
/**
|
|
886
886
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
887
887
|
*
|
|
888
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
889
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
890
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
891
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
892
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
893
|
+
*
|
|
888
894
|
* @param guards Guards corresponding to each tuple position.
|
|
889
895
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
890
896
|
*/
|
package/dist/index.d.ts
CHANGED
|
@@ -885,6 +885,12 @@ export declare function typedStruct<T extends object>(): <const S extends TypedS
|
|
|
885
885
|
/**
|
|
886
886
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
887
887
|
*
|
|
888
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
889
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
890
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
891
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
892
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
893
|
+
*
|
|
888
894
|
* @param guards Guards corresponding to each tuple position.
|
|
889
895
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
890
896
|
*/
|
package/dist/index.js
CHANGED
|
@@ -39,6 +39,19 @@ const objectToString = Object.prototype.toString;
|
|
|
39
39
|
*/
|
|
40
40
|
const getTag = (value) => objectToString.call(value);
|
|
41
41
|
//#endregion
|
|
42
|
+
//#region src/utils/object-prototype.ts
|
|
43
|
+
const OBJECT_CONSTRUCTOR_SOURCE = Function.prototype.toString.call(Object);
|
|
44
|
+
/**
|
|
45
|
+
* Checks whether an object is `Object.prototype` from any realm.
|
|
46
|
+
*
|
|
47
|
+
* @param prototype Object to check.
|
|
48
|
+
* @returns Whether `prototype` is an `Object.prototype`.
|
|
49
|
+
*/
|
|
50
|
+
const isObjectPrototype = (prototype) => {
|
|
51
|
+
const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
|
|
52
|
+
return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === OBJECT_CONSTRUCTOR_SOURCE;
|
|
53
|
+
};
|
|
54
|
+
//#endregion
|
|
42
55
|
//#region src/core/object.ts
|
|
43
56
|
const BUILTIN_BRAND_SENTINEL = Object.freeze({});
|
|
44
57
|
const nativeIsError = Error.isError;
|
|
@@ -89,7 +102,8 @@ const readObjectProperty = (value, key) => {
|
|
|
89
102
|
const isPlainObject = define((value) => {
|
|
90
103
|
if (!isObject(value)) return false;
|
|
91
104
|
const proto = Object.getPrototypeOf(value);
|
|
92
|
-
|
|
105
|
+
if (proto === null || proto === Object.prototype) return true;
|
|
106
|
+
return Object.getPrototypeOf(proto) === null && isObjectPrototype(proto);
|
|
93
107
|
});
|
|
94
108
|
/**
|
|
95
109
|
* Checks whether a value is an array.
|
|
@@ -816,7 +830,7 @@ const createSetPredicate = (items) => {
|
|
|
816
830
|
});
|
|
817
831
|
};
|
|
818
832
|
function oneOfValues(...args) {
|
|
819
|
-
const items = normalizeValues(args);
|
|
833
|
+
const items = [...normalizeValues(args)];
|
|
820
834
|
return items.length <= ONE_OF_VALUES_LINEAR_SCAN_MAX ? createLinearPredicate(items) : createSetPredicate(items);
|
|
821
835
|
}
|
|
822
836
|
//#endregion
|
|
@@ -847,11 +861,6 @@ function setOf(valueGuard) {
|
|
|
847
861
|
}
|
|
848
862
|
//#endregion
|
|
849
863
|
//#region src/core/combinators/struct.ts
|
|
850
|
-
const OBJECT_CONSTRUCTOR_SOURCE = Function.prototype.toString.call(Object);
|
|
851
|
-
const isObjectPrototype = (prototype) => {
|
|
852
|
-
const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
|
|
853
|
-
return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === OBJECT_CONSTRUCTOR_SOURCE;
|
|
854
|
-
};
|
|
855
864
|
const hasOnlyEnumerableOwnStringKeys = (schema) => Object.getOwnPropertyNames(schema).every((key) => Object.prototype.propertyIsEnumerable.call(schema, key));
|
|
856
865
|
const hasInheritedStringKeys = (schema) => {
|
|
857
866
|
let prototype = Object.getPrototypeOf(schema);
|
|
@@ -980,6 +989,12 @@ function typedStruct() {
|
|
|
980
989
|
/**
|
|
981
990
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
982
991
|
*
|
|
992
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
993
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
994
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
995
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
996
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
997
|
+
*
|
|
983
998
|
* @param guards Guards corresponding to each tuple position.
|
|
984
999
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
985
1000
|
*/
|
package/dist/index.mjs
CHANGED
|
@@ -38,6 +38,19 @@ const objectToString = Object.prototype.toString;
|
|
|
38
38
|
*/
|
|
39
39
|
const getTag = (value) => objectToString.call(value);
|
|
40
40
|
//#endregion
|
|
41
|
+
//#region src/utils/object-prototype.ts
|
|
42
|
+
const OBJECT_CONSTRUCTOR_SOURCE = Function.prototype.toString.call(Object);
|
|
43
|
+
/**
|
|
44
|
+
* Checks whether an object is `Object.prototype` from any realm.
|
|
45
|
+
*
|
|
46
|
+
* @param prototype Object to check.
|
|
47
|
+
* @returns Whether `prototype` is an `Object.prototype`.
|
|
48
|
+
*/
|
|
49
|
+
const isObjectPrototype = (prototype) => {
|
|
50
|
+
const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
|
|
51
|
+
return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === OBJECT_CONSTRUCTOR_SOURCE;
|
|
52
|
+
};
|
|
53
|
+
//#endregion
|
|
41
54
|
//#region src/core/object.ts
|
|
42
55
|
const BUILTIN_BRAND_SENTINEL = Object.freeze({});
|
|
43
56
|
const nativeIsError = Error.isError;
|
|
@@ -88,7 +101,8 @@ const readObjectProperty = (value, key) => {
|
|
|
88
101
|
const isPlainObject = define((value) => {
|
|
89
102
|
if (!isObject(value)) return false;
|
|
90
103
|
const proto = Object.getPrototypeOf(value);
|
|
91
|
-
|
|
104
|
+
if (proto === null || proto === Object.prototype) return true;
|
|
105
|
+
return Object.getPrototypeOf(proto) === null && isObjectPrototype(proto);
|
|
92
106
|
});
|
|
93
107
|
/**
|
|
94
108
|
* Checks whether a value is an array.
|
|
@@ -815,7 +829,7 @@ const createSetPredicate = (items) => {
|
|
|
815
829
|
});
|
|
816
830
|
};
|
|
817
831
|
function oneOfValues(...args) {
|
|
818
|
-
const items = normalizeValues(args);
|
|
832
|
+
const items = [...normalizeValues(args)];
|
|
819
833
|
return items.length <= ONE_OF_VALUES_LINEAR_SCAN_MAX ? createLinearPredicate(items) : createSetPredicate(items);
|
|
820
834
|
}
|
|
821
835
|
//#endregion
|
|
@@ -846,11 +860,6 @@ function setOf(valueGuard) {
|
|
|
846
860
|
}
|
|
847
861
|
//#endregion
|
|
848
862
|
//#region src/core/combinators/struct.ts
|
|
849
|
-
const OBJECT_CONSTRUCTOR_SOURCE = Function.prototype.toString.call(Object);
|
|
850
|
-
const isObjectPrototype = (prototype) => {
|
|
851
|
-
const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
|
|
852
|
-
return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === OBJECT_CONSTRUCTOR_SOURCE;
|
|
853
|
-
};
|
|
854
863
|
const hasOnlyEnumerableOwnStringKeys = (schema) => Object.getOwnPropertyNames(schema).every((key) => Object.prototype.propertyIsEnumerable.call(schema, key));
|
|
855
864
|
const hasInheritedStringKeys = (schema) => {
|
|
856
865
|
let prototype = Object.getPrototypeOf(schema);
|
|
@@ -979,6 +988,12 @@ function typedStruct() {
|
|
|
979
988
|
/**
|
|
980
989
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
981
990
|
*
|
|
991
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
992
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
993
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
994
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
995
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
996
|
+
*
|
|
982
997
|
* @param guards Guards corresponding to each tuple position.
|
|
983
998
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
984
999
|
*/
|
package/package.json
CHANGED