is-kit 1.14.2 → 1.14.3

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/dist/index.js CHANGED
@@ -1,672 +1,876 @@
1
- "use strict";
2
- var __defProp = Object.defineProperty;
3
- var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
- var __getOwnPropNames = Object.getOwnPropertyNames;
5
- var __hasOwnProp = Object.prototype.hasOwnProperty;
6
- var __export = (target, all) => {
7
- for (var name in all)
8
- __defProp(target, name, { get: all[name], enumerable: true });
9
- };
10
- var __copyProps = (to, from, except, desc) => {
11
- if (from && typeof from === "object" || typeof from === "function") {
12
- for (let key of __getOwnPropNames(from))
13
- if (!__hasOwnProp.call(to, key) && key !== except)
14
- __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
- }
16
- return to;
17
- };
18
- var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
-
20
- // src/index.ts
21
- var index_exports = {};
22
- __export(index_exports, {
23
- and: () => and,
24
- andAll: () => andAll,
25
- arrayOf: () => arrayOf,
26
- assert: () => assert,
27
- define: () => define,
28
- equals: () => equals,
29
- equalsBy: () => equalsBy,
30
- equalsKey: () => equalsKey,
31
- everyArrayValue: () => everyArrayValue,
32
- everyMapEntry: () => everyMapEntry,
33
- everyOwnEnumerableEntry: () => everyOwnEnumerableEntry,
34
- everySetValue: () => everySetValue,
35
- everyTupleValue: () => everyTupleValue,
36
- guardIn: () => guardIn,
37
- hasKey: () => hasKey,
38
- hasKeys: () => hasKeys,
39
- isArray: () => isArray,
40
- isArrayBuffer: () => isArrayBuffer,
41
- isAsyncIterable: () => isAsyncIterable,
42
- isBigInt: () => isBigInt,
43
- isBlob: () => isBlob,
44
- isBoolean: () => isBoolean,
45
- isDataView: () => isDataView,
46
- isDate: () => isDate,
47
- isError: () => isError,
48
- isFile: () => isFile,
49
- isFiniteNumber: () => isFiniteNumber,
50
- isFunction: () => isFunction,
51
- isInfiniteNumber: () => isInfiniteNumber,
52
- isInstanceOf: () => isInstanceOf,
53
- isInteger: () => isInteger,
54
- isIterable: () => isIterable,
55
- isMap: () => isMap,
56
- isNaN: () => isNaN,
57
- isNegative: () => isNegative,
58
- isNil: () => isNil,
59
- isNotNil: () => isNotNil,
60
- isNull: () => isNull,
61
- isNumber: () => isNumber,
62
- isNumberPrimitive: () => isNumberPrimitive,
63
- isObject: () => isObject,
64
- isPlainObject: () => isPlainObject,
65
- isPositive: () => isPositive,
66
- isPrimitive: () => isPrimitive,
67
- isPromiseLike: () => isPromiseLike,
68
- isRegExp: () => isRegExp,
69
- isSafeInteger: () => isSafeInteger,
70
- isSet: () => isSet,
71
- isString: () => isString,
72
- isSymbol: () => isSymbol,
73
- isTypedArray: () => isTypedArray,
74
- isURL: () => isURL,
75
- isUndefined: () => isUndefined,
76
- isWeakMap: () => isWeakMap,
77
- isWeakSet: () => isWeakSet,
78
- isZero: () => isZero,
79
- lazy: () => lazy,
80
- mapOf: () => mapOf,
81
- narrowKeyTo: () => narrowKeyTo,
82
- nonEmptyArrayOf: () => nonEmptyArrayOf,
83
- nonNull: () => nonNull,
84
- not: () => not,
85
- nullable: () => nullable,
86
- nullish: () => nullish,
87
- oneOf: () => oneOf,
88
- oneOfValues: () => oneOfValues,
89
- optional: () => optional,
90
- optionalKey: () => optionalKey,
91
- or: () => or,
92
- predicateToRefine: () => predicateToRefine,
93
- recordOf: () => recordOf,
94
- refineDefinedKey: () => refineDefinedKey,
95
- refineIndex: () => refineIndex,
96
- refineKey: () => refineKey,
97
- required: () => required,
98
- safeJsonParse: () => safeJsonParse,
99
- safeParse: () => safeParse,
100
- safeParseWith: () => safeParseWith,
101
- setOf: () => setOf,
102
- struct: () => struct,
103
- toBooleanPredicates: () => toBooleanPredicates,
104
- tupleOf: () => tupleOf,
105
- typedStruct: () => typedStruct
106
- });
107
- module.exports = __toCommonJS(index_exports);
108
1
 
109
- // src/core/assert.ts
110
- var DEFAULT_ASSERT_MESSAGE = "Assertion failed";
2
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
3
+ //#region src/core/assert.ts
4
+ const DEFAULT_ASSERT_MESSAGE = "Assertion failed";
111
5
  function assert(fn, value, message) {
112
- if (fn(value)) return;
113
- throw new Error(message ?? DEFAULT_ASSERT_MESSAGE);
6
+ if (fn(value)) return;
7
+ throw new Error(message ?? DEFAULT_ASSERT_MESSAGE);
114
8
  }
115
-
116
- // src/core/define.ts
9
+ //#endregion
10
+ //#region src/core/define.ts
117
11
  function define(fn) {
118
- return (value) => !!fn(value);
119
- }
120
-
121
- // src/utils/own-properties.ts
122
- var hasOwnPropertyKey = (value, key) => Object.hasOwn(value, key);
123
- var hasOwnPropertyKeys = (value, keys) => keys.every((key) => hasOwnPropertyKey(value, key));
124
-
125
- // src/utils/object-tags.ts
126
- var objectToString = Object.prototype.toString;
127
- var OBJECT_TAG_ERROR = "[object Error]";
128
- var getTag = (value) => objectToString.call(value);
129
-
130
- // src/core/object.ts
131
- var BUILTIN_BRAND_SENTINEL = Object.freeze({});
132
- var getIntrinsicGetter = (prototype, key) => {
133
- const getter = Object.getOwnPropertyDescriptor(prototype, key)?.get;
134
- return getter ?? (() => {
135
- throw new TypeError(`Missing intrinsic getter: ${String(key)}`);
136
- });
12
+ return (value) => !!fn(value);
13
+ }
14
+ //#endregion
15
+ //#region src/utils/own-properties.ts
16
+ /**
17
+ * Checks whether an object has an own property key.
18
+ *
19
+ * @param value Object-like value already narrowed by callers.
20
+ * @param key Property key to check.
21
+ * @returns Whether `key` is present directly on `value`.
22
+ */
23
+ const hasOwnPropertyKey = (value, key) => Object.hasOwn(value, key);
24
+ /**
25
+ * Checks whether an object has every requested own property key.
26
+ *
27
+ * @param value Object-like value already narrowed by callers.
28
+ * @param keys Property keys to check.
29
+ * @returns Whether all keys are present directly on `value`.
30
+ */
31
+ const hasOwnPropertyKeys = (value, keys) => keys.every((key) => hasOwnPropertyKey(value, key));
32
+ //#endregion
33
+ //#region src/utils/object-tags.ts
34
+ const objectToString = Object.prototype.toString;
35
+ /**
36
+ * Returns the internal object tag for a value.
37
+ * @param value Value to inspect with `Object.prototype.toString`.
38
+ * @returns Stable built-in tag such as `[object Date]`.
39
+ */
40
+ const getTag = (value) => objectToString.call(value);
41
+ //#endregion
42
+ //#region src/core/object.ts
43
+ const BUILTIN_BRAND_SENTINEL = Object.freeze({});
44
+ const getIntrinsicGetter = (prototype, key) => {
45
+ return Object.getOwnPropertyDescriptor(prototype, key)?.get ?? (() => {
46
+ throw new TypeError(`Missing intrinsic getter: ${String(key)}`);
47
+ });
137
48
  };
138
- var defineIntrinsicBrandGuard = (checkBrand) => define((value) => {
139
- try {
140
- checkBrand(value);
141
- return true;
142
- } catch {
143
- return false;
144
- }
49
+ const defineIntrinsicBrandGuard = (checkBrand) => define((value) => {
50
+ try {
51
+ checkBrand(value);
52
+ return true;
53
+ } catch {
54
+ return false;
55
+ }
145
56
  });
146
- var dateGetTime = Date.prototype.getTime;
147
- var mapHas = Map.prototype.has;
148
- var setHas = Set.prototype.has;
149
- var weakMapHas = WeakMap.prototype.has;
150
- var weakSetHas = WeakSet.prototype.has;
151
- var regExpSource = getIntrinsicGetter(RegExp.prototype, "source");
152
- var arrayBufferByteLength = getIntrinsicGetter(
153
- ArrayBuffer.prototype,
154
- "byteLength"
155
- );
156
- var dataViewBuffer = getIntrinsicGetter(DataView.prototype, "buffer");
157
- var typedArrayName = Object.getOwnPropertyDescriptor(
158
- Object.getPrototypeOf(Uint8Array.prototype),
159
- Symbol.toStringTag
160
- )?.get;
161
- var defineOptionalInstanceGuard = (constructor) => constructor === void 0 ? define(() => false) : define(
162
- (value) => typeof constructor === "function" && value instanceof constructor
163
- );
164
- var isFunction = define(
165
- (value) => typeof value === "function"
166
- );
167
- var isObject = define(
168
- (value) => typeof value === "object" && value !== null
169
- );
170
- var readObjectProperty = (value, key) => {
171
- if (!isObject(value) && !isFunction(value)) return void 0;
172
- return value[key];
57
+ const dateGetTime = Date.prototype.getTime;
58
+ const mapHas = Map.prototype.has;
59
+ const setHas = Set.prototype.has;
60
+ const weakMapHas = WeakMap.prototype.has;
61
+ const weakSetHas = WeakSet.prototype.has;
62
+ const regExpSource = getIntrinsicGetter(RegExp.prototype, "source");
63
+ const arrayBufferByteLength = getIntrinsicGetter(ArrayBuffer.prototype, "byteLength");
64
+ const dataViewBuffer = getIntrinsicGetter(DataView.prototype, "buffer");
65
+ const typedArrayName = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), Symbol.toStringTag)?.get;
66
+ const defineOptionalInstanceGuard = (constructor) => constructor === void 0 ? define(() => false) : define((value) => typeof constructor === "function" && value instanceof constructor);
67
+ /**
68
+ * Checks whether a value is a function.
69
+ *
70
+ * @returns Predicate narrowing to a callable value.
71
+ */
72
+ const isFunction = define((value) => typeof value === "function");
73
+ /**
74
+ * Checks for non-null objects (including arrays, dates, etc.).
75
+ *
76
+ * @returns Predicate narrowing to `Record<PropertyKey, unknown>`.
77
+ */
78
+ const isObject = define((value) => typeof value === "object" && value !== null);
79
+ const readObjectProperty = (value, key) => {
80
+ if (!isObject(value) && !isFunction(value)) return void 0;
81
+ return value[key];
173
82
  };
174
- var isPlainObject = define((value) => {
175
- if (!isObject(value)) return false;
176
- const proto = Object.getPrototypeOf(value);
177
- return proto === null || Object.getPrototypeOf(proto) === null;
83
+ /**
84
+ * Checks for plain objects created by object literals or `Object.create(null)`.
85
+ *
86
+ * @returns Predicate narrowing to `Record<string, unknown>`.
87
+ */
88
+ const isPlainObject = define((value) => {
89
+ if (!isObject(value)) return false;
90
+ const proto = Object.getPrototypeOf(value);
91
+ return proto === null || Object.getPrototypeOf(proto) === null;
178
92
  });
179
- var isArray = define(Array.isArray);
180
- var isDate = define((value) => {
181
- try {
182
- return !Number.isNaN(dateGetTime.call(value));
183
- } catch {
184
- return false;
185
- }
93
+ /**
94
+ * Checks whether a value is an array.
95
+ *
96
+ * @returns Predicate narrowing to `readonly unknown[]`.
97
+ */
98
+ const isArray = define(Array.isArray);
99
+ /**
100
+ * Checks whether a value is a valid `Date` instance (not `Invalid Date`).
101
+ *
102
+ * @returns Predicate narrowing to `Date`.
103
+ */
104
+ const isDate = define((value) => {
105
+ try {
106
+ return !Number.isNaN(dateGetTime.call(value));
107
+ } catch {
108
+ return false;
109
+ }
186
110
  });
187
- var isRegExp = defineIntrinsicBrandGuard(
188
- (value) => regExpSource.call(value)
189
- );
190
- var isMap = defineIntrinsicBrandGuard(
191
- (value) => mapHas.call(value, BUILTIN_BRAND_SENTINEL)
192
- );
193
- var isSet = defineIntrinsicBrandGuard(
194
- (value) => setHas.call(value, BUILTIN_BRAND_SENTINEL)
195
- );
196
- var isWeakMap = defineIntrinsicBrandGuard(
197
- (value) => weakMapHas.call(value, BUILTIN_BRAND_SENTINEL)
198
- );
199
- var isWeakSet = defineIntrinsicBrandGuard(
200
- (value) => weakSetHas.call(value, BUILTIN_BRAND_SENTINEL)
201
- );
202
- var isPromiseLike = define(
203
- (value) => isFunction(readObjectProperty(value, "then"))
204
- );
205
- var isIterable = define(
206
- (value) => isFunction(readObjectProperty(value, Symbol.iterator))
207
- );
208
- var isAsyncIterable = define(
209
- (value) => isFunction(readObjectProperty(value, Symbol.asyncIterator))
210
- );
211
- var isArrayBuffer = defineIntrinsicBrandGuard(
212
- (value) => arrayBufferByteLength.call(value)
213
- );
214
- var isDataView = defineIntrinsicBrandGuard(
215
- (value) => dataViewBuffer.call(value)
216
- );
217
- var isTypedArray = define(
218
- (value) => typedArrayName?.call(value) !== void 0
219
- );
220
- var isError = define(
221
- (value) => value instanceof Error || getTag(value) === OBJECT_TAG_ERROR
222
- );
223
- var isURL = defineOptionalInstanceGuard(
224
- typeof URL === "undefined" ? void 0 : URL
225
- );
226
- var isBlob = defineOptionalInstanceGuard(
227
- typeof Blob === "undefined" ? void 0 : Blob
228
- );
229
- var isFile = defineOptionalInstanceGuard(
230
- typeof File === "undefined" ? void 0 : File
231
- );
232
- var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
233
-
234
- // src/core/equals.ts
235
- var guardedBy = (guard) => define((input) => guard(input));
111
+ /**
112
+ * Checks whether a value is a `RegExp`.
113
+ *
114
+ * @returns Predicate narrowing to `RegExp`.
115
+ */
116
+ const isRegExp = defineIntrinsicBrandGuard((value) => regExpSource.call(value));
117
+ /**
118
+ * Checks whether a value is a `Map`.
119
+ *
120
+ * @returns Predicate narrowing to `Map<unknown, unknown>`.
121
+ */
122
+ const isMap = defineIntrinsicBrandGuard((value) => mapHas.call(value, BUILTIN_BRAND_SENTINEL));
123
+ /**
124
+ * Checks whether a value is a `Set`.
125
+ *
126
+ * @returns Predicate narrowing to `Set<unknown>`.
127
+ */
128
+ const isSet = defineIntrinsicBrandGuard((value) => setHas.call(value, BUILTIN_BRAND_SENTINEL));
129
+ /**
130
+ * Checks whether a value is a `WeakMap`.
131
+ *
132
+ * @returns Predicate narrowing to `WeakMap<object, unknown>`.
133
+ */
134
+ const isWeakMap = defineIntrinsicBrandGuard((value) => weakMapHas.call(value, BUILTIN_BRAND_SENTINEL));
135
+ /**
136
+ * Checks whether a value is a `WeakSet`.
137
+ *
138
+ * @returns Predicate narrowing to `WeakSet<object>`.
139
+ */
140
+ const isWeakSet = defineIntrinsicBrandGuard((value) => weakSetHas.call(value, BUILTIN_BRAND_SENTINEL));
141
+ /**
142
+ * Checks whether a value is promise-like (has a `then` function).
143
+ *
144
+ * @returns Predicate narrowing to `PromiseLike<unknown>`.
145
+ */
146
+ const isPromiseLike = define((value) => isFunction(readObjectProperty(value, "then")));
147
+ /**
148
+ * Checks whether a value implements the `Iterable` protocol.
149
+ *
150
+ * @returns Predicate narrowing to `Iterable<unknown>`.
151
+ */
152
+ const isIterable = define((value) => isFunction(readObjectProperty(value, Symbol.iterator)));
153
+ /**
154
+ * Checks whether a value implements the `AsyncIterable` protocol.
155
+ *
156
+ * @returns Predicate narrowing to `AsyncIterable<unknown>`.
157
+ */
158
+ const isAsyncIterable = define((value) => isFunction(readObjectProperty(value, Symbol.asyncIterator)));
159
+ /**
160
+ * Checks whether a value is an `ArrayBuffer`.
161
+ *
162
+ * @returns Predicate narrowing to `ArrayBuffer`.
163
+ */
164
+ const isArrayBuffer = defineIntrinsicBrandGuard((value) => arrayBufferByteLength.call(value));
165
+ /**
166
+ * Checks whether a value is a `DataView`.
167
+ *
168
+ * @returns Predicate narrowing to `DataView`.
169
+ */
170
+ const isDataView = defineIntrinsicBrandGuard((value) => dataViewBuffer.call(value));
171
+ /**
172
+ * Checks whether a value is a typed array view (any `ArrayBufferView` except DataView).
173
+ *
174
+ * @returns Predicate narrowing to `ArrayBufferView`.
175
+ */
176
+ const isTypedArray = define((value) => typedArrayName?.call(value) !== void 0);
177
+ /**
178
+ * Checks whether a value is an `Error` (instance of Error or plain Error object tag).
179
+ *
180
+ * @returns Predicate narrowing to `Error`.
181
+ */
182
+ const isError = define((value) => value instanceof Error || getTag(value) === "[object Error]");
183
+ /**
184
+ * Checks whether a value is a `URL` (in environments with URL available).
185
+ *
186
+ * @returns Predicate narrowing to `URL` when supported; otherwise always false.
187
+ */
188
+ const isURL = defineOptionalInstanceGuard(typeof URL === "undefined" ? void 0 : URL);
189
+ /**
190
+ * Checks whether a value is a `Blob` (in environments with Blob available).
191
+ *
192
+ * @returns Predicate narrowing to `Blob` when supported; otherwise always false.
193
+ */
194
+ const isBlob = defineOptionalInstanceGuard(typeof Blob === "undefined" ? void 0 : Blob);
195
+ /**
196
+ * Checks whether a value is a `File` (in environments with File available).
197
+ *
198
+ * @returns Predicate narrowing to `File` when supported; otherwise always false.
199
+ */
200
+ const isFile = defineOptionalInstanceGuard(typeof File === "undefined" ? void 0 : File);
201
+ /**
202
+ * Creates a guard that checks whether a value is an instance of `constructor`.
203
+ *
204
+ * @param constructor Constructor used as the right-hand side of `instanceof`.
205
+ * @returns Predicate narrowing to `InstanceType<C>`.
206
+ */
207
+ const isInstanceOf = (constructor) => define((value) => value instanceof constructor);
208
+ //#endregion
209
+ //#region src/core/equals.ts
210
+ const guardedBy = (guard) => define((input) => guard(input));
211
+ /**
212
+ * Creates a guard that matches values equal to the provided target using `Object.is` semantics.
213
+ *
214
+ * @param target Target value to compare against.
215
+ * @returns Predicate narrowing to the exact literal type of `target`.
216
+ */
236
217
  function equals(target) {
237
- return define((input) => Object.is(input, target));
218
+ return define((input) => Object.is(input, target));
238
219
  }
239
220
  function equalsBy(guard, selector) {
240
- const matchesGuard = guardedBy(guard);
241
- const createComparator = (selectorFn) => (target) => define((input) => {
242
- if (!matchesGuard(input)) return false;
243
- return Object.is(selectorFn(input), target);
244
- });
245
- if (selector) {
246
- return createComparator(selector);
247
- }
248
- return (selectorFn) => createComparator(selectorFn);
221
+ const matchesGuard = guardedBy(guard);
222
+ const createComparator = (selectorFn) => (target) => define((input) => {
223
+ if (!matchesGuard(input)) return false;
224
+ return Object.is(selectorFn(input), target);
225
+ });
226
+ if (selector) return createComparator(selector);
227
+ return (selectorFn) => createComparator(selectorFn);
249
228
  }
250
229
  function equalsKey(key, target) {
251
- return define((input) => {
252
- return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
253
- });
230
+ return define((input) => {
231
+ return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
232
+ });
254
233
  }
255
-
256
- // src/core/key-guards.ts
234
+ //#endregion
235
+ //#region src/core/key-guards.ts
257
236
  function hasKey(key) {
258
- return define(
259
- (input) => isObject(input) && hasOwnPropertyKey(input, key)
260
- );
237
+ return define((input) => isObject(input) && hasOwnPropertyKey(input, key));
261
238
  }
262
239
  function hasKeys(...keys) {
263
- if (keys.length === 0) {
264
- return define(() => false);
265
- }
266
- return define(
267
- (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
268
- );
240
+ if (keys.length === 0) return define(() => false);
241
+ return define((input) => isObject(input) && hasOwnPropertyKeys(input, keys));
269
242
  }
270
243
  function narrowKeyTo(guard, key) {
271
- return (target) => {
272
- const keyEquals = equalsKey(key, target);
273
- return define(
274
- (input) => guard(input) && keyEquals(input)
275
- );
276
- };
277
- }
278
-
279
- // src/core/property-refinement.ts
244
+ return (target) => {
245
+ const keyEquals = equalsKey(key, target);
246
+ return define((input) => guard(input) && keyEquals(input));
247
+ };
248
+ }
249
+ //#endregion
250
+ //#region src/core/property-refinement.ts
251
+ /**
252
+ * Lifts a required-property refinement to its parent object.
253
+ * @param key Single literal key of the required property to refine.
254
+ * @param refinement Refinement applied to the property value.
255
+ * @returns Refinement that preserves the parent type and narrows the property.
256
+ * @example
257
+ * const hasStringValue = refineKey('value', isString);
258
+ */
280
259
  function refineKey(key, refinement) {
281
- return (value) => refinement(value[key]);
282
- }
260
+ return (value) => refinement(value[key]);
261
+ }
262
+ /**
263
+ * Lifts a defined optional-property refinement to its parent object.
264
+ * @param key Single literal key of the optional property to refine when defined.
265
+ * @param refinement Refinement applied only to a defined property value.
266
+ * @returns Refinement that requires and narrows the property.
267
+ * @example
268
+ * const hasDefinedStringLabel = refineDefinedKey('label', isString);
269
+ */
283
270
  function refineDefinedKey(key, refinement) {
284
- return (value) => {
285
- const property = value[key];
286
- return property !== void 0 && refinement(property);
287
- };
288
- }
271
+ return (value) => {
272
+ const property = value[key];
273
+ return property !== void 0 && refinement(property);
274
+ };
275
+ }
276
+ /**
277
+ * Refines one defined own element of a readonly array.
278
+ * @param index Non-negative integer literal identifying the own element.
279
+ * @param refinement Refinement applied only to a defined element.
280
+ * @returns Refinement that narrows the selected index.
281
+ * @example
282
+ * const hasStringAtZero = refineIndex(0, isString);
283
+ */
289
284
  function refineIndex(index, refinement) {
290
- return (value) => {
291
- if (!hasOwnPropertyKey(value, index)) return false;
292
- const element = value[index];
293
- return element !== void 0 && refinement(element);
294
- };
295
- }
296
-
297
- // src/core/lazy.ts
285
+ return (value) => {
286
+ if (!hasOwnPropertyKey(value, index)) return false;
287
+ const element = value[index];
288
+ return element !== void 0 && refinement(element);
289
+ };
290
+ }
291
+ //#endregion
292
+ //#region src/core/lazy.ts
293
+ /**
294
+ * Creates a predicate whose implementation is initialized on first use.
295
+ *
296
+ * The initialized predicate is cached after the factory returns successfully.
297
+ * Circular references in the input value are not detected.
298
+ *
299
+ * @param factory Function that creates the predicate when it is first evaluated.
300
+ * @returns Predicate that delegates to the lazily initialized implementation.
301
+ */
298
302
  function lazy(factory) {
299
- let predicate;
300
- return (value) => {
301
- predicate ??= factory();
302
- return predicate(value);
303
- };
304
- }
305
-
306
- // src/core/logic.ts
303
+ let predicate;
304
+ return (value) => {
305
+ predicate ??= factory();
306
+ return predicate(value);
307
+ };
308
+ }
309
+ //#endregion
310
+ //#region src/core/logic.ts
307
311
  function and(precondition, condition) {
308
- return (input) => !!(precondition(input) && condition(input));
312
+ return (input) => !!(precondition(input) && condition(input));
309
313
  }
310
314
  function andAll(precondition, stepOrSteps, ...remainingSteps) {
311
- const steps = stepOrSteps === void 0 ? remainingSteps : isFunction(stepOrSteps) ? [stepOrSteps, ...remainingSteps] : [...stepOrSteps, ...remainingSteps];
312
- return (input) => {
313
- if (!precondition(input)) return false;
314
- return steps.every((step) => step(input));
315
- };
315
+ const steps = stepOrSteps === void 0 ? remainingSteps : isFunction(stepOrSteps) ? [stepOrSteps, ...remainingSteps] : [...stepOrSteps, ...remainingSteps];
316
+ return (input) => {
317
+ if (!precondition(input)) return false;
318
+ return steps.every((step) => step(input));
319
+ };
316
320
  }
317
321
  function or(...refinements) {
318
- return (input) => refinements.some((refinement) => refinement(input));
322
+ return (input) => refinements.some((refinement) => refinement(input));
319
323
  }
320
324
  function guardIn() {
321
- return (guard) => (input) => guard(input);
325
+ return (guard) => (input) => guard(input);
322
326
  }
323
327
  function not(fn) {
324
- return (input) => !fn(input);
328
+ return (input) => !fn(input);
325
329
  }
326
-
327
- // src/core/nullish.ts
330
+ //#endregion
331
+ //#region src/core/nullish.ts
328
332
  function nullable(fn) {
329
- return (value) => value === null || fn(value);
333
+ return (value) => value === null || fn(value);
330
334
  }
331
335
  function nonNull(fn) {
332
- return (value) => value !== null && fn(value);
336
+ return (value) => value !== null && fn(value);
333
337
  }
334
338
  function nullish(fn) {
335
- return (value) => value === null || value === void 0 || fn(value);
339
+ return (value) => value === null || value === void 0 || fn(value);
336
340
  }
337
341
  function optional(fn) {
338
- return (value) => value === void 0 || fn(value);
342
+ return (value) => value === void 0 || fn(value);
339
343
  }
340
344
  function required(fn) {
341
- return (value) => value !== void 0 && fn(value);
345
+ return (value) => value !== void 0 && fn(value);
342
346
  }
343
-
344
- // src/core/parse.ts
347
+ //#endregion
348
+ //#region src/core/parse.ts
345
349
  function safeParse(fn, value) {
346
- const valid = fn(value);
347
- return valid ? { valid: true, value } : { valid: false };
350
+ return fn(value) ? {
351
+ valid: true,
352
+ value
353
+ } : { valid: false };
348
354
  }
349
355
  function safeParseWith(fn) {
350
- return (value) => safeParse(fn, value);
351
- }
356
+ return (value) => safeParse(fn, value);
357
+ }
358
+ /**
359
+ * Decodes JSON text and validates the decoded value without coercion.
360
+ *
361
+ * @param input JSON text to decode.
362
+ * @param guard Guard used to validate the decoded `unknown` value.
363
+ * @returns The decoded value when valid; `{ valid: false }` for invalid JSON or a guard mismatch.
364
+ */
352
365
  function safeJsonParse(input, guard) {
353
- let value;
354
- try {
355
- value = JSON.parse(input);
356
- } catch {
357
- return { valid: false };
358
- }
359
- return safeParse(guard, value);
360
- }
361
-
362
- // src/core/predicate.ts
363
- var predicateToRefine = (fn) => (value) => fn(value);
364
-
365
- // src/core/primitive.ts
366
- var isString = define((value) => typeof value === "string");
367
- var isNumberPrimitive = define(
368
- (value) => typeof value === "number"
369
- );
370
- var isNaN = define(Number.isNaN);
371
- var isInfiniteNumber = and(
372
- isNumberPrimitive,
373
- predicateToRefine((n) => n === Infinity || n === -Infinity)
374
- );
375
- var isFiniteNumber = predicateToRefine(Number.isFinite);
376
- var isNumber = and(isNumberPrimitive, isFiniteNumber);
377
- var isInteger = define(Number.isInteger);
378
- var isSafeInteger = define(Number.isSafeInteger);
379
- var isPositive = and(
380
- isNumber,
381
- predicateToRefine((n) => n > 0)
382
- );
383
- var isNegative = and(
384
- isNumber,
385
- predicateToRefine((n) => n < 0)
386
- );
387
- var isZero = and(
388
- isNumber,
389
- predicateToRefine((n) => n === 0)
390
- );
391
- var isBoolean = define((value) => typeof value === "boolean");
392
- var isBigInt = define((value) => typeof value === "bigint");
393
- var isSymbol = define((value) => typeof value === "symbol");
394
- var isUndefined = define((value) => value === void 0);
395
- var isNull = define((value) => value === null);
396
- var isNil = (value) => value === null || value === void 0;
397
- var isNotNil = (value) => value !== null && value !== void 0;
398
- var isPrimitive = or(
399
- isString,
400
- isNumberPrimitive,
401
- isBoolean,
402
- isBigInt,
403
- isSymbol,
404
- isUndefined,
405
- isNull
406
- );
407
-
408
- // src/utils/guard-collections.ts
409
- var mapEntries = Map.prototype.entries;
410
- var setValues = Set.prototype.values;
411
- var everyIterableValue = (values, predicate) => {
412
- for (const value of values) {
413
- if (!predicate(value)) return false;
414
- }
415
- return true;
366
+ let value;
367
+ try {
368
+ value = JSON.parse(input);
369
+ } catch {
370
+ return { valid: false };
371
+ }
372
+ return safeParse(guard, value);
373
+ }
374
+ //#endregion
375
+ //#region src/core/predicate.ts
376
+ /**
377
+ * Converts a boolean predicate into a refinement preserving the input type.
378
+ *
379
+ * @param fn Boolean-returning function over a value of type A.
380
+ * @returns Refinement equivalent to the provided predicate.
381
+ */
382
+ const predicateToRefine = (fn) => (value) => fn(value);
383
+ //#endregion
384
+ //#region src/core/primitive.ts
385
+ /**
386
+ * Checks whether a value is a string.
387
+ *
388
+ * @returns Predicate narrowing to `string`.
389
+ */
390
+ const isString = define((value) => typeof value === "string");
391
+ /**
392
+ * Checks whether a value is a number primitive (may include NaN/±Infinity).
393
+ *
394
+ * @returns Predicate narrowing to `number` (primitive-only).
395
+ */
396
+ const isNumberPrimitive = define((value) => typeof value === "number");
397
+ /**
398
+ * Checks whether a value is `NaN`.
399
+ *
400
+ * Equivalent to `Number.isNaN(value)` without coercion.
401
+ * @returns Predicate narrowing to `number` (`NaN` only).
402
+ */
403
+ const isNaN = define(Number.isNaN);
404
+ /**
405
+ * Checks whether a value is an infinite number (±Infinity).
406
+ *
407
+ * @returns Predicate narrowing to `number` (Infinity or -Infinity).
408
+ */
409
+ const isInfiniteNumber = and(isNumberPrimitive, predicateToRefine((n) => n === Infinity || n === -Infinity));
410
+ /**
411
+ * Checks whether a number is finite.
412
+ * @returns Refinement that accepts only finite numbers.
413
+ */
414
+ const isFiniteNumber = predicateToRefine(Number.isFinite);
415
+ /**
416
+ * Checks whether a value is a finite number.
417
+ * @returns Predicate narrowing to finite `number`.
418
+ */
419
+ const isNumber = and(isNumberPrimitive, isFiniteNumber);
420
+ /**
421
+ * Checks whether a value is an integer number.
422
+ *
423
+ * Equivalent to `Number.isInteger(value)`.
424
+ * @returns Predicate narrowing to integer `number`.
425
+ */
426
+ const isInteger = define(Number.isInteger);
427
+ /**
428
+ * Checks whether a value is a safe integer.
429
+ *
430
+ * Equivalent to `Number.isSafeInteger(value)`.
431
+ * @returns Predicate narrowing to safe-integer `number`.
432
+ */
433
+ const isSafeInteger = define(Number.isSafeInteger);
434
+ /**
435
+ * Checks whether a value is a positive finite number (> 0).
436
+ *
437
+ * Uses `isNumber` internally to exclude NaN and ±Infinity.
438
+ * @returns Predicate narrowing to positive `number`.
439
+ */
440
+ const isPositive = and(isNumber, predicateToRefine((n) => n > 0));
441
+ /**
442
+ * Checks whether a value is a negative finite number (< 0).
443
+ *
444
+ * Uses `isNumber` internally to exclude NaN and ±Infinity.
445
+ * Note: `-0` is not considered negative (consistent with `< 0`).
446
+ * @returns Predicate narrowing to negative `number`.
447
+ */
448
+ const isNegative = and(isNumber, predicateToRefine((n) => n < 0));
449
+ /**
450
+ * Checks whether a value is a finite number that equals zero (including `-0`).
451
+ *
452
+ * @returns Predicate narrowing to zero `number`.
453
+ */
454
+ const isZero = and(isNumber, predicateToRefine((n) => n === 0));
455
+ /**
456
+ * Checks whether a value is a boolean.
457
+ *
458
+ * @returns Predicate narrowing to `boolean`.
459
+ */
460
+ const isBoolean = define((value) => typeof value === "boolean");
461
+ /**
462
+ * Checks whether a value is a bigint.
463
+ *
464
+ * @returns Predicate narrowing to `bigint`.
465
+ */
466
+ const isBigInt = define((value) => typeof value === "bigint");
467
+ /**
468
+ * Checks whether a value is a symbol.
469
+ *
470
+ * @returns Predicate narrowing to `symbol`.
471
+ */
472
+ const isSymbol = define((value) => typeof value === "symbol");
473
+ /**
474
+ * Checks whether a value is exactly `undefined`.
475
+ *
476
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
477
+ * {@link or} once and reuse it.
478
+ *
479
+ * @returns Predicate narrowing to `undefined`.
480
+ * @see isNil
481
+ */
482
+ const isUndefined = define((value) => value === void 0);
483
+ /**
484
+ * Checks whether a value is exactly `null`.
485
+ *
486
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
487
+ * {@link or} once and reuse it.
488
+ *
489
+ * @returns Predicate narrowing to `null`.
490
+ * @see isNil
491
+ */
492
+ const isNull = define((value) => value === null);
493
+ /**
494
+ * Checks whether a value is `null` or `undefined` (nullish).
495
+ *
496
+ * Prefer this over hand-rolling `isNull(x) || isUndefined(x)`: it is the same
497
+ * check expressed once. To widen an existing guard so it also accepts nullish
498
+ * values, use {@link nullish} instead.
499
+ *
500
+ * @returns Predicate narrowing to `null | undefined`.
501
+ * @example
502
+ * isNil(null); // true
503
+ * isNil(undefined); // true
504
+ * isNil(0); // false
505
+ */
506
+ const isNil = (value) => value === null || value === void 0;
507
+ /**
508
+ * Checks whether a value is neither `null` nor `undefined`.
509
+ *
510
+ * Narrows the input to `NonNullable<T>`, making it useful for removing nullish
511
+ * values with `Array.prototype.filter`.
512
+ *
513
+ * @param value Value to check.
514
+ * @returns `true` when the value is not nullish.
515
+ * @example
516
+ * const values: Array<string | null | undefined> = ['value', null];
517
+ * const presentValues = values.filter(isNotNil); // string[]
518
+ * @see isNil
519
+ */
520
+ const isNotNil = (value) => value !== null && value !== void 0;
521
+ /**
522
+ * Checks whether a value is a JavaScript primitive.
523
+ *
524
+ * Primitives: string, number, boolean, bigint, symbol, undefined, null.
525
+ * Note: `number` here includes NaN and ±Infinity (use `isNumber` for finite only).
526
+ *
527
+ * @returns Predicate narrowing to `Primitive`.
528
+ */
529
+ const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
530
+ //#endregion
531
+ //#region src/utils/guard-collections.ts
532
+ const mapEntries = Map.prototype.entries;
533
+ const setValues = Set.prototype.values;
534
+ const everyIterableValue = (values, predicate) => {
535
+ for (const value of values) if (!predicate(value)) return false;
536
+ return true;
416
537
  };
417
- var everyKeyValueEntry = (entries, predicate) => {
418
- for (const [key, value] of entries) {
419
- if (!predicate(key, value)) return false;
420
- }
421
- return true;
538
+ const everyKeyValueEntry = (entries, predicate) => {
539
+ for (const [key, value] of entries) if (!predicate(key, value)) return false;
540
+ return true;
422
541
  };
423
- var everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
424
- var everyTupleValue = (values, predicates) => {
425
- if (values.length !== predicates.length) return false;
426
- for (let index = 0; index < predicates.length; index += 1) {
427
- const predicate = predicates[index];
428
- if (!predicate(values[index])) return false;
429
- }
430
- return true;
542
+ /**
543
+ * Checks whether every array element satisfies the provided predicate.
544
+ *
545
+ * @deprecated Use `Array.prototype.every` for boolean iteration or `arrayOf`
546
+ * for a narrowing guard. This root export will be removed in is-kit v2.
547
+ * @param values Array values to validate.
548
+ * @param predicate Predicate applied to each element.
549
+ * @returns Whether all elements satisfy `predicate`.
550
+ */
551
+ const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
552
+ /**
553
+ * Checks whether a tuple matches the provided element predicates in order.
554
+ *
555
+ * @deprecated Use `tupleOf` for a narrowing guard or compare the tuple length
556
+ * and predicates directly. This root export will be removed in is-kit v2.
557
+ * @param values Tuple candidate values.
558
+ * @param predicates Predicates aligned to each tuple index.
559
+ * @returns Whether lengths match and each index passes.
560
+ */
561
+ const everyTupleValue = (values, predicates) => {
562
+ if (values.length !== predicates.length) return false;
563
+ for (let index = 0; index < predicates.length; index += 1) {
564
+ const predicate = predicates[index];
565
+ if (!predicate(values[index])) return false;
566
+ }
567
+ return true;
431
568
  };
432
- var everySetValue = (values, predicate) => everyIterableValue(values, predicate);
433
- var everyBrandedSetValue = (values, predicate) => everyIterableValue(setValues.call(values), predicate);
434
- var everyMapEntry = (values, keyPredicate, valuePredicate) => everyKeyValueEntry(
435
- values,
436
- (key, value) => keyPredicate(key) && valuePredicate(value)
437
- );
438
- var everyBrandedMapEntry = (values, keyPredicate, valuePredicate) => everyKeyValueEntry(
439
- mapEntries.call(values),
440
- (key, value) => keyPredicate(key) && valuePredicate(value)
441
- );
442
- var everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyIterableValue(
443
- Object.keys(values),
444
- (key) => keyPredicate(key) && valuePredicate(values[key])
445
- );
446
-
447
- // src/core/combinators/array.ts
569
+ /**
570
+ * Checks whether every set value satisfies the provided predicate.
571
+ *
572
+ * @deprecated Use `setOf` for a narrowing guard or iterate the set directly.
573
+ * This root export will be removed in is-kit v2.
574
+ * @param values Set values to validate.
575
+ * @param predicate Predicate applied to each value.
576
+ * @returns Whether all set values satisfy `predicate`.
577
+ */
578
+ const everySetValue = (values, predicate) => everyIterableValue(values, predicate);
579
+ /**
580
+ * Checks built-in Set data without invoking an instance-provided iterator.
581
+ * WHY: A branded Set subclass may override its public iterator and throw.
582
+ */
583
+ const everyBrandedSetValue = (values, predicate) => everyIterableValue(setValues.call(values), predicate);
584
+ /**
585
+ * Checks whether every map entry satisfies the provided key and value predicates.
586
+ *
587
+ * @deprecated Use `mapOf` for a narrowing guard or iterate the map directly.
588
+ * This root export will be removed in is-kit v2.
589
+ * @param values Map values to validate.
590
+ * @param keyPredicate Predicate applied to each key.
591
+ * @param valuePredicate Predicate applied to each value.
592
+ * @returns Whether all keys and values satisfy their predicates.
593
+ */
594
+ const everyMapEntry = (values, keyPredicate, valuePredicate) => everyKeyValueEntry(values, (key, value) => keyPredicate(key) && valuePredicate(value));
595
+ /**
596
+ * Checks built-in Map data without invoking an instance-provided iterator.
597
+ * WHY: A branded Map subclass may override its public iterator and throw.
598
+ */
599
+ const everyBrandedMapEntry = (values, keyPredicate, valuePredicate) => everyKeyValueEntry(mapEntries.call(values), (key, value) => keyPredicate(key) && valuePredicate(value));
600
+ /**
601
+ * Checks whether every own enumerable string key/value pair satisfies the provided predicates.
602
+ *
603
+ * @deprecated Use `recordOf` for a narrowing guard or
604
+ * `Object.entries(value).every(...)` for boolean iteration. This root export
605
+ * will be removed in is-kit v2.
606
+ * @param values Plain object values to validate.
607
+ * @param keyPredicate Predicate applied to each enumerable own string key.
608
+ * @param valuePredicate Predicate applied to each corresponding value.
609
+ * @returns Whether all enumerable entries satisfy their predicates.
610
+ */
611
+ const everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyIterableValue(Object.keys(values), (key) => keyPredicate(key) && valuePredicate(values[key]));
612
+ //#endregion
613
+ //#region src/core/combinators/array.ts
614
+ /**
615
+ * Validates an array where every element satisfies the provided guard.
616
+ *
617
+ * @param elementGuard Guard applied to each array element.
618
+ * @returns Predicate narrowing to a readonly array of the guarded element type.
619
+ */
448
620
  function arrayOf(elementGuard) {
449
- return define(
450
- (input) => Array.isArray(input) && everyArrayValue(input, elementGuard)
451
- );
452
- }
621
+ return define((input) => Array.isArray(input) && everyArrayValue(input, elementGuard));
622
+ }
623
+ /**
624
+ * Validates a non-empty array where every element satisfies the provided guard.
625
+ *
626
+ * @param elementGuard Guard applied to each array element.
627
+ * @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
628
+ */
453
629
  function nonEmptyArrayOf(elementGuard) {
454
- return define(
455
- (input) => Array.isArray(input) && input.length > 0 && everyArrayValue(input, elementGuard)
456
- );
457
- }
458
-
459
- // src/core/combinators/map.ts
630
+ return define((input) => Array.isArray(input) && input.length > 0 && everyArrayValue(input, elementGuard));
631
+ }
632
+ //#endregion
633
+ //#region src/core/combinators/map.ts
634
+ /**
635
+ * Validates a map where every key and value satisfies the provided guards.
636
+ *
637
+ * @param keyGuard Guard applied to each map key.
638
+ * @param valueGuard Guard applied to each map value.
639
+ * @returns Predicate narrowing to a readonly map with guarded key/value types.
640
+ */
460
641
  function mapOf(keyGuard, valueGuard) {
461
- return define(
462
- (input) => isMap(input) && everyBrandedMapEntry(input, keyGuard, valueGuard)
463
- );
642
+ return define((input) => isMap(input) && everyBrandedMapEntry(input, keyGuard, valueGuard));
464
643
  }
465
-
466
- // src/core/combinators/one-of.ts
644
+ //#endregion
645
+ //#region src/core/combinators/one-of.ts
467
646
  function oneOf(...refinements) {
468
- return (input) => refinements.some((refinement) => refinement(input));
469
- }
470
-
471
- // src/core/combinators/one-of-values.ts
472
- var ONE_OF_VALUES_LINEAR_SCAN_MAX = 8;
473
- var isSingleArrayArg = define(
474
- (value) => Array.isArray(value) && value.length === 1 && Array.isArray(value[0])
475
- );
476
- var normalizeValues = (args) => isSingleArrayArg(args) ? args[0] : args;
477
- var createLinearPredicate = (items) => {
478
- return define((input) => {
479
- return items.some((value) => Object.is(value, input));
480
- });
647
+ return (input) => refinements.some((refinement) => refinement(input));
648
+ }
649
+ //#endregion
650
+ //#region src/core/combinators/one-of-values.ts
651
+ const ONE_OF_VALUES_LINEAR_SCAN_MAX = 8;
652
+ const isSingleArrayArg = define((value) => Array.isArray(value) && value.length === 1 && Array.isArray(value[0]));
653
+ const normalizeValues = (args) => isSingleArrayArg(args) ? args[0] : args;
654
+ const createLinearPredicate = (items) => {
655
+ return define((input) => {
656
+ return items.some((value) => Object.is(value, input));
657
+ });
481
658
  };
482
- var createSetPredicate = (items) => {
483
- let hasPositiveZero = false;
484
- let hasNegativeZero = false;
485
- const valueSet = /* @__PURE__ */ new Set();
486
- for (const literalValue of items) {
487
- if (isZero(literalValue)) {
488
- if (Object.is(literalValue, -0)) hasNegativeZero = true;
489
- else hasPositiveZero = true;
490
- } else {
491
- valueSet.add(literalValue);
492
- }
493
- }
494
- return define((input) => {
495
- if (isZero(input)) {
496
- return Object.is(input, -0) ? hasNegativeZero : hasPositiveZero;
497
- }
498
- return valueSet.has(input);
499
- });
659
+ const createSetPredicate = (items) => {
660
+ let hasPositiveZero = false;
661
+ let hasNegativeZero = false;
662
+ const valueSet = /* @__PURE__ */ new Set();
663
+ for (const literalValue of items) if (isZero(literalValue)) {
664
+ if (Object.is(literalValue, -0)) hasNegativeZero = true;
665
+ else hasPositiveZero = true;
666
+ } else valueSet.add(literalValue);
667
+ return define((input) => {
668
+ if (isZero(input)) return Object.is(input, -0) ? hasNegativeZero : hasPositiveZero;
669
+ return valueSet.has(input);
670
+ });
500
671
  };
501
672
  function oneOfValues(...args) {
502
- const items = normalizeValues(args);
503
- return items.length <= ONE_OF_VALUES_LINEAR_SCAN_MAX ? createLinearPredicate(items) : createSetPredicate(items);
504
- }
505
-
506
- // src/core/combinators/record.ts
673
+ const items = normalizeValues(args);
674
+ return items.length <= ONE_OF_VALUES_LINEAR_SCAN_MAX ? createLinearPredicate(items) : createSetPredicate(items);
675
+ }
676
+ //#endregion
677
+ //#region src/core/combinators/record.ts
678
+ /**
679
+ * Validates a record-like object by guarding both keys and values.
680
+ *
681
+ * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
682
+ * @param valueFunction Guard applied to each value in the record.
683
+ * @returns Predicate narrowing to a readonly record with guarded key/value types.
684
+ */
507
685
  function recordOf(keyFunction, valueFunction) {
508
- return define(
509
- (input) => isPlainObject(input) && everyOwnEnumerableEntry(input, keyFunction, valueFunction)
510
- );
511
- }
512
-
513
- // src/core/combinators/set.ts
686
+ return define((input) => isPlainObject(input) && everyOwnEnumerableEntry(input, keyFunction, valueFunction));
687
+ }
688
+ //#endregion
689
+ //#region src/core/combinators/set.ts
690
+ /**
691
+ * Validates a set where every value satisfies the provided guard.
692
+ *
693
+ * @param valueGuard Guard applied to each set value.
694
+ * @returns Predicate narrowing to a readonly set of the guarded value type.
695
+ */
514
696
  function setOf(valueGuard) {
515
- return define(
516
- (input) => isSet(input) && everyBrandedSetValue(input, valueGuard)
517
- );
518
- }
519
-
520
- // src/core/combinators/struct.ts
521
- var isOptionalSchemaField = define(
522
- // WHY: Optional fields are represented as a small tagged object so `struct`
523
- // can distinguish schema metadata from plain predicate functions up front.
524
- (field) => isObject(field) && field.optional === true && isFunction(field.guard)
525
- );
526
- var hasRequiredKeys = (obj, entries) => (
527
- // WHY: Required fields must be own properties; inherited values should not
528
- // satisfy a schema because `struct` models object payload shape, not prototype chains.
529
- entries.every(
530
- ([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key])
531
- )
532
- );
533
- var hasValidOptionalKeys = (obj, entries) => (
534
- // WHY: Optional keys are validated only when present. Missing keys stay valid
535
- // without forcing callers to encode `undefined` into the value guard.
536
- entries.every(
537
- ([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key])
538
- )
539
- );
540
- var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
697
+ return define((input) => isSet(input) && everyBrandedSetValue(input, valueGuard));
698
+ }
699
+ //#endregion
700
+ //#region src/core/combinators/struct.ts
701
+ const isOptionalSchemaField = define((field) => isObject(field) && field.optional === true && isFunction(field.guard));
702
+ const hasRequiredKeys = (obj, entries) => entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]));
703
+ const hasValidOptionalKeys = (obj, entries) => entries.every(([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key]));
704
+ const hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
705
+ /**
706
+ * Marks a struct schema field as optional at the key level.
707
+ *
708
+ * When used inside `struct`, the property may be absent. If the property exists,
709
+ * its value must satisfy the wrapped guard.
710
+ *
711
+ * @param guard Guard used to validate the property value when the key exists.
712
+ * @returns Schema field marker understood by `struct`.
713
+ */
541
714
  function optionalKey(guard) {
542
- return { optional: true, guard };
543
- }
715
+ return {
716
+ optional: true,
717
+ guard
718
+ };
719
+ }
720
+ /**
721
+ * Validates an object against a field-to-guard schema.
722
+ * Keys in the schema are required unless wrapped with `optionalKey`; optionally
723
+ * rejects extra keys when `exact: true`.
724
+ *
725
+ * @param schema Record of property guards.
726
+ * @param options When `{ exact: true }`, disallows own enumerable string-key
727
+ * properties not in `schema`.
728
+ * @returns Predicate that narrows to the inferred struct type.
729
+ */
544
730
  function struct(schema, options) {
545
- const requiredEntries = [];
546
- const optionalEntries = [];
547
- const schemaKeys = [];
548
- for (const key in schema) {
549
- if (!hasOwnPropertyKey(schema, key)) continue;
550
- const field = schema[key];
551
- schemaKeys.push(key);
552
- if (isOptionalSchemaField(field)) {
553
- optionalEntries.push([key, field.guard]);
554
- continue;
555
- }
556
- requiredEntries.push([key, field]);
557
- }
558
- const allowed = options?.exact ? new Set(schemaKeys) : null;
559
- return define((input) => {
560
- if (!isPlainObject(input)) return false;
561
- const obj = input;
562
- if (!hasRequiredKeys(obj, requiredEntries)) return false;
563
- if (!hasValidOptionalKeys(obj, optionalEntries)) return false;
564
- if (!allowed) return true;
565
- return hasOnlyAllowedKeys(obj, allowed);
566
- });
567
- }
568
-
569
- // src/core/combinators/typed-struct.ts
731
+ const requiredEntries = [];
732
+ const optionalEntries = [];
733
+ const schemaKeys = [];
734
+ for (const key in schema) {
735
+ if (!hasOwnPropertyKey(schema, key)) continue;
736
+ const field = schema[key];
737
+ schemaKeys.push(key);
738
+ if (isOptionalSchemaField(field)) {
739
+ optionalEntries.push([key, field.guard]);
740
+ continue;
741
+ }
742
+ requiredEntries.push([key, field]);
743
+ }
744
+ const allowed = options?.exact ? new Set(schemaKeys) : null;
745
+ return define((input) => {
746
+ if (!isPlainObject(input)) return false;
747
+ const obj = input;
748
+ if (!hasRequiredKeys(obj, requiredEntries)) return false;
749
+ if (!hasValidOptionalKeys(obj, optionalEntries)) return false;
750
+ if (!allowed) return true;
751
+ return hasOnlyAllowedKeys(obj, allowed);
752
+ });
753
+ }
754
+ //#endregion
755
+ //#region src/core/combinators/typed-struct.ts
756
+ /**
757
+ * Creates a `struct` builder checked against an existing string-keyed object
758
+ * type. Numeric and symbol properties are excluded from the checked shape and
759
+ * cannot be validated by the resulting guard.
760
+ * Optional target keys must also be declared with `optionalKey` so type drift
761
+ * stays visible when the target type changes.
762
+ *
763
+ * Target-compatible field guards may narrow further than the target field type;
764
+ * the returned predicate preserves those narrower inferred types.
765
+ *
766
+ * @returns Builder that rejects missing, extra, or incompatible struct fields.
767
+ */
570
768
  function typedStruct() {
571
- return (fields, options) => (
572
- // WHY: `typedStruct` keeps `struct` runtime behavior while using the target
573
- // type only to check that hand-written guard fields stay in sync.
574
- struct(fields, options)
575
- );
576
- }
577
-
578
- // src/core/combinators/tuple.ts
769
+ return (fields, options) => struct(fields, options);
770
+ }
771
+ //#endregion
772
+ //#region src/core/combinators/tuple.ts
773
+ /**
774
+ * Validates a fixed-length tuple by applying element-wise guards.
775
+ *
776
+ * @param guards Guards corresponding to each tuple position.
777
+ * @returns Predicate that narrows to a readonly tuple of guarded element types.
778
+ */
579
779
  function tupleOf(...guards) {
580
- return define(
581
- (input) => Array.isArray(input) && everyTupleValue(input, guards)
582
- );
583
- }
584
-
585
- // src/utils/to-boolean-predicates.ts
586
- var toBooleanPredicates = (predicates) => predicates;
587
- // Annotate the CommonJS export names for ESM import in node:
588
- 0 && (module.exports = {
589
- and,
590
- andAll,
591
- arrayOf,
592
- assert,
593
- define,
594
- equals,
595
- equalsBy,
596
- equalsKey,
597
- everyArrayValue,
598
- everyMapEntry,
599
- everyOwnEnumerableEntry,
600
- everySetValue,
601
- everyTupleValue,
602
- guardIn,
603
- hasKey,
604
- hasKeys,
605
- isArray,
606
- isArrayBuffer,
607
- isAsyncIterable,
608
- isBigInt,
609
- isBlob,
610
- isBoolean,
611
- isDataView,
612
- isDate,
613
- isError,
614
- isFile,
615
- isFiniteNumber,
616
- isFunction,
617
- isInfiniteNumber,
618
- isInstanceOf,
619
- isInteger,
620
- isIterable,
621
- isMap,
622
- isNaN,
623
- isNegative,
624
- isNil,
625
- isNotNil,
626
- isNull,
627
- isNumber,
628
- isNumberPrimitive,
629
- isObject,
630
- isPlainObject,
631
- isPositive,
632
- isPrimitive,
633
- isPromiseLike,
634
- isRegExp,
635
- isSafeInteger,
636
- isSet,
637
- isString,
638
- isSymbol,
639
- isTypedArray,
640
- isURL,
641
- isUndefined,
642
- isWeakMap,
643
- isWeakSet,
644
- isZero,
645
- lazy,
646
- mapOf,
647
- narrowKeyTo,
648
- nonEmptyArrayOf,
649
- nonNull,
650
- not,
651
- nullable,
652
- nullish,
653
- oneOf,
654
- oneOfValues,
655
- optional,
656
- optionalKey,
657
- or,
658
- predicateToRefine,
659
- recordOf,
660
- refineDefinedKey,
661
- refineIndex,
662
- refineKey,
663
- required,
664
- safeJsonParse,
665
- safeParse,
666
- safeParseWith,
667
- setOf,
668
- struct,
669
- toBooleanPredicates,
670
- tupleOf,
671
- typedStruct
672
- });
780
+ return define((input) => Array.isArray(input) && everyTupleValue(input, guards));
781
+ }
782
+ //#endregion
783
+ //#region src/utils/to-boolean-predicates.ts
784
+ /**
785
+ * Converts predicates to plain boolean predicates for iteration helpers.
786
+ *
787
+ * @deprecated Use the original predicate array directly. This identity helper
788
+ * will no longer be exported from the package root in is-kit v2.
789
+ * @param predicates Predicates to be treated as simple boolean functions.
790
+ * @returns Readonly array of boolean-returning functions.
791
+ */
792
+ const toBooleanPredicates = (predicates) => predicates;
793
+ //#endregion
794
+ exports.and = and;
795
+ exports.andAll = andAll;
796
+ exports.arrayOf = arrayOf;
797
+ exports.assert = assert;
798
+ exports.define = define;
799
+ exports.equals = equals;
800
+ exports.equalsBy = equalsBy;
801
+ exports.equalsKey = equalsKey;
802
+ exports.everyArrayValue = everyArrayValue;
803
+ exports.everyMapEntry = everyMapEntry;
804
+ exports.everyOwnEnumerableEntry = everyOwnEnumerableEntry;
805
+ exports.everySetValue = everySetValue;
806
+ exports.everyTupleValue = everyTupleValue;
807
+ exports.guardIn = guardIn;
808
+ exports.hasKey = hasKey;
809
+ exports.hasKeys = hasKeys;
810
+ exports.isArray = isArray;
811
+ exports.isArrayBuffer = isArrayBuffer;
812
+ exports.isAsyncIterable = isAsyncIterable;
813
+ exports.isBigInt = isBigInt;
814
+ exports.isBlob = isBlob;
815
+ exports.isBoolean = isBoolean;
816
+ exports.isDataView = isDataView;
817
+ exports.isDate = isDate;
818
+ exports.isError = isError;
819
+ exports.isFile = isFile;
820
+ exports.isFiniteNumber = isFiniteNumber;
821
+ exports.isFunction = isFunction;
822
+ exports.isInfiniteNumber = isInfiniteNumber;
823
+ exports.isInstanceOf = isInstanceOf;
824
+ exports.isInteger = isInteger;
825
+ exports.isIterable = isIterable;
826
+ exports.isMap = isMap;
827
+ exports.isNaN = isNaN;
828
+ exports.isNegative = isNegative;
829
+ exports.isNil = isNil;
830
+ exports.isNotNil = isNotNil;
831
+ exports.isNull = isNull;
832
+ exports.isNumber = isNumber;
833
+ exports.isNumberPrimitive = isNumberPrimitive;
834
+ exports.isObject = isObject;
835
+ exports.isPlainObject = isPlainObject;
836
+ exports.isPositive = isPositive;
837
+ exports.isPrimitive = isPrimitive;
838
+ exports.isPromiseLike = isPromiseLike;
839
+ exports.isRegExp = isRegExp;
840
+ exports.isSafeInteger = isSafeInteger;
841
+ exports.isSet = isSet;
842
+ exports.isString = isString;
843
+ exports.isSymbol = isSymbol;
844
+ exports.isTypedArray = isTypedArray;
845
+ exports.isURL = isURL;
846
+ exports.isUndefined = isUndefined;
847
+ exports.isWeakMap = isWeakMap;
848
+ exports.isWeakSet = isWeakSet;
849
+ exports.isZero = isZero;
850
+ exports.lazy = lazy;
851
+ exports.mapOf = mapOf;
852
+ exports.narrowKeyTo = narrowKeyTo;
853
+ exports.nonEmptyArrayOf = nonEmptyArrayOf;
854
+ exports.nonNull = nonNull;
855
+ exports.not = not;
856
+ exports.nullable = nullable;
857
+ exports.nullish = nullish;
858
+ exports.oneOf = oneOf;
859
+ exports.oneOfValues = oneOfValues;
860
+ exports.optional = optional;
861
+ exports.optionalKey = optionalKey;
862
+ exports.or = or;
863
+ exports.predicateToRefine = predicateToRefine;
864
+ exports.recordOf = recordOf;
865
+ exports.refineDefinedKey = refineDefinedKey;
866
+ exports.refineIndex = refineIndex;
867
+ exports.refineKey = refineKey;
868
+ exports.required = required;
869
+ exports.safeJsonParse = safeJsonParse;
870
+ exports.safeParse = safeParse;
871
+ exports.safeParseWith = safeParseWith;
872
+ exports.setOf = setOf;
873
+ exports.struct = struct;
874
+ exports.toBooleanPredicates = toBooleanPredicates;
875
+ exports.tupleOf = tupleOf;
876
+ exports.typedStruct = typedStruct;