is-kit 1.15.3 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -386,6 +386,10 @@ Use `struct(schema, { exact: true })` when extra own enumerable string keys
386
386
  should be rejected. Exact mode follows `Object.keys(...)` semantics, so symbol
387
387
  keys and non-enumerable properties are outside its key matching.
388
388
 
389
+ Schemas themselves must use own enumerable string keys. `struct` rejects
390
+ symbol-keyed, non-enumerable, and inherited schema fields so its runtime checks
391
+ match the inferred type.
392
+
389
393
  If the property must exist but the value may be `undefined`, use `optional(guard)` instead.
390
394
 
391
395
  ### 5. Validate arrays, tuples, maps, sets, and records
@@ -579,7 +583,13 @@ Use `discriminatedUnion<T>()` with `typedStruct` to keep both the branch
579
583
  fields and the union coverage aligned with an existing TypeScript type.
580
584
 
581
585
  ```ts
582
- import { discriminatedUnion, isNumber, oneOfValues, typedStruct } from 'is-kit';
586
+ import {
587
+ discriminatedUnion,
588
+ discriminatedUnionWithFallback,
589
+ isNumber,
590
+ oneOfValues,
591
+ typedStruct
592
+ } from 'is-kit';
583
593
 
584
594
  type Event =
585
595
  { kind: 'click'; x: number; y: number } | { kind: 'scroll'; delta: number };
@@ -611,6 +621,55 @@ For a `__proto__` discriminant, write the branch as `['__proto__']: guard` (or
611
621
  use a null-prototype map); the uncomputed object-literal form changes the
612
622
  object's prototype instead of creating a branch entry.
613
623
 
624
+ #### Classify explicit fallback variants
625
+
626
+ Use `discriminatedUnionWithFallback<T>()` when an input may contain future
627
+ discriminant values. Known branches remain exhaustive. An undeclared own
628
+ primitive discriminant instead calls `fallback.create`, which returns payload
629
+ for one canonical fallback tag or `undefined` to mark the input invalid. The
630
+ payload must be an own data-field plain record with an `Object.prototype` or
631
+ null prototype; arrays, dates, functions, class instances, custom prototypes,
632
+ accessor fields, and function fields are rejected so the decoded value always
633
+ matches its object shape. Dictionary
634
+ payload _types_ with broad or patterned index signatures are also unsupported;
635
+ use a finite object shape for each fallback variant.
636
+
637
+ ```ts
638
+ const classifyEvent = discriminatedUnionWithFallback<Event>()(
639
+ 'kind',
640
+ ['click', 'scroll'],
641
+ {
642
+ click: typedStruct<Extract<Event, { kind: 'click' }>>()({
643
+ kind: oneOfValues('click'),
644
+ x: isNumber,
645
+ y: isNumber
646
+ }),
647
+ scroll: typedStruct<Extract<Event, { kind: 'scroll' }>>()({
648
+ kind: oneOfValues('scroll'),
649
+ delta: isNumber
650
+ })
651
+ },
652
+ {
653
+ tag: 'unknown',
654
+ create: (input, originalKind) => ({ input, originalKind })
655
+ }
656
+ );
657
+
658
+ const result = classifyEvent(value);
659
+ if (result.valid) {
660
+ const event = result.value;
661
+ // Event member | { kind: 'unknown'; input: unknown; originalKind: PropertyKey | boolean }
662
+ }
663
+ ```
664
+
665
+ The fallback tag must be one literal with a distinct runtime key from every
666
+ known discriminant, so a known `1` also reserves the tag `'1'` (and `true`
667
+ reserves `'true'`). The classifier determines whether a raw discriminant is
668
+ known before converting it to a branch key, then writes the fallback tag after
669
+ creating its payload. A malformed known branch, missing or inherited
670
+ discriminant, non-primitive discriminant, or non-plain fallback payload returns
671
+ `{ valid: false }` without producing a fallback variant.
672
+
614
673
  ### 12. Narrow object keys
615
674
 
616
675
  Use key helpers when the important part of a value is one property.
@@ -785,6 +844,12 @@ For detailed API pages and more examples, see:
785
844
  Start with [How to safely filter null and undefined from arrays in
786
845
  TypeScript](https://is-kit.dev/guides/filter-null-and-undefined).
787
846
 
847
+ ## Compatibility
848
+
849
+ is-kit requires Node.js 22 or later. CI validates the packed npm artifact on
850
+ Node.js 22.x and 24.x with native ESM, CommonJS, and strict TypeScript
851
+ NodeNext consumers.
852
+
788
853
  ## 👨‍💻 Development
789
854
 
790
855
  Requires Node 22.22.0 and pnpm 11.2.2.
package/dist/index.d.mts CHANGED
@@ -739,6 +739,22 @@ type MatchingDiscriminantMember<T extends object, K extends DiscriminantKey<T>,
739
739
  type DiscriminatedUnionGuardMap<T extends object, K extends DiscriminantKey<T>, Values extends DiscriminantValue> = { readonly [Value in Values as DiscriminantMapKey<Value>]: Predicate<MatchingDiscriminantMember<T, K, Value>>; };
740
740
  type InvalidGuardDiscriminantValues<K extends PropertyKey, Values extends DiscriminantValue, G extends object> = { [Value in Values as DiscriminantMapKey<Value>]: G extends Record<DiscriminantMapKey<Value>, infer Guard> ? GuardedOf<Guard> extends Record<K, DiscriminantValue> ? Value extends GuardedOf<Guard>[K] ? never : Value : Value : Value; }[DiscriminantMapKey<Values>];
741
741
  type GuardsMatchDiscriminantValues<K extends PropertyKey, Values extends DiscriminantValue, G extends object> = [InvalidGuardDiscriminantValues<K, Values, G>] extends [never] ? unknown : never;
742
+ type FallbackDiscriminant<Values extends DiscriminantValue, Value extends DiscriminantValue> = IsFiniteDiscriminantValue<Value> extends true ? IsUnion<Value> extends false ? DiscriminantRuntimeKey<Value> extends DiscriminantRuntimeKey<Values> ? never : unknown : never : never;
743
+ type RuntimePropertyKey<Key extends PropertyKey> = Key extends symbol ? Key : Key extends string | number ? `${Key}` : never;
744
+ type OmitRuntimeKey<Data extends object, Key extends PropertyKey> = { [Property in keyof Data as RuntimePropertyKey<Property> extends RuntimePropertyKey<Key> ? never : Property]: Data[Property]; };
745
+ type InvalidFallbackKey<Key extends PropertyKey> = Key extends unknown ? SinglePropertyKey<Key> extends never ? Key : never : never;
746
+ type InvalidFallbackData<Data extends object> = Data extends unknown ? [InvalidFallbackKey<keyof Data & PropertyKey>] extends [never] ? never : Data : never;
747
+ type FiniteFallbackData<Data extends object> = [InvalidFallbackData<Data>] extends [never] ? unknown : never;
748
+ type FallbackVariant<K extends PropertyKey, Value extends DiscriminantValue, Data extends Record<PropertyKey, unknown>> = Data extends unknown ? OmitRuntimeKey<Data, K> & Record<K, Value> : never;
749
+ type FallbackVariantConfig<Values extends DiscriminantValue, Value extends DiscriminantValue, Data extends Record<PropertyKey, unknown>> = {
750
+ readonly tag: Value & FallbackDiscriminant<Values, Value>;
751
+ readonly create: (this: void, input: unknown, discriminant: DiscriminantValue) => Data | undefined;
752
+ };
753
+ type Decoder<Output> = (input: unknown) => ParseResult<Output>;
754
+ declare const invalidFallbackClassifier: unique symbol;
755
+ type InvalidFallbackClassifier = {
756
+ readonly [invalidFallbackClassifier]: 'Fallback payloads must have finite property keys.';
757
+ };
742
758
  /**
743
759
  * Creates an exhaustive guard for a union whose members share a literal discriminant.
744
760
  * A tuple of every discriminant value keeps finite coverage explicit at runtime
@@ -752,6 +768,16 @@ type GuardsMatchDiscriminantValues<K extends PropertyKey, Values extends Discrim
752
768
  * @returns Predicate narrowing to the union accepted by the branch guards.
753
769
  */
754
770
  export declare function discriminatedUnion<T extends object>(): <const K extends DiscriminantKey<T>, const Values extends readonly DiscriminantValue[], const G extends DiscriminatedUnionGuardMap<T, K, Values[number]>>(discriminant: K, values: Values & ExactDiscriminantValues<T, K, Values>, guards: NoExtraKeys<G, DiscriminatedUnionGuardMap<T, K, Values[number]>> & NonCollidingDiscriminants<T, K> & GuardsMatchDiscriminantValues<K, Values[number], G>) => Predicate<GuardedOf<G[keyof G]>>;
771
+ /**
772
+ * Classifies a finite discriminated union and explicitly transforms undeclared values into one fallback variant.
773
+ * Known values remain exhaustive: a malformed known member fails instead of reaching the fallback.
774
+ * @param discriminant Required property that identifies each known union member.
775
+ * @param values Finite tuple containing every known discriminant value.
776
+ * @param guards Branch guards keyed by the known discriminant values.
777
+ * @param fallback Canonical fallback tag and receiver-free factory for an own non-function data-field payload; return `undefined` to reject the input.
778
+ * @returns Decoder that returns a guarded known member or fallback variant when valid.
779
+ */
780
+ export declare function discriminatedUnionWithFallback<T extends object>(): <const K extends DiscriminantKey<T>, const Values extends readonly DiscriminantValue[], const G extends DiscriminatedUnionGuardMap<T, K, Values[number]>, const FallbackValue extends DiscriminantValue, const FallbackData extends Record<PropertyKey, unknown>>(discriminant: K & SinglePropertyKey<K>, values: Values & ExactDiscriminantValues<T, K, Values>, guards: NoExtraKeys<G, DiscriminatedUnionGuardMap<T, K, Values[number]>> & NonCollidingDiscriminants<T, K> & GuardsMatchDiscriminantValues<K, Values[number], G>, fallback: FallbackVariantConfig<Values[number], FallbackValue, FallbackData>) => FiniteFallbackData<FallbackData> extends never ? InvalidFallbackClassifier : Decoder<GuardedOf<G[keyof G]> | FallbackVariant<K, FallbackValue, FallbackData>>;
755
781
  //#endregion
756
782
  //#region src/core/combinators/map.d.ts
757
783
  /**
@@ -822,16 +848,17 @@ export declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Pr
822
848
  */
823
849
  export declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
824
850
  /**
825
- * Validates an object against a field-to-guard schema with string runtime keys.
826
- * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
827
- * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
828
- * rejects extra keys when `exact: true`.
851
+ * Validates an object against a field-to-guard schema with own enumerable string
852
+ * keys. Numeric schema keys are normalized to strings by JavaScript; symbol,
853
+ * non-enumerable, and inherited fields are not supported. Keys are required unless
854
+ * wrapped with `optionalKey`; optionally rejects extra keys when `exact: true`.
829
855
  *
830
856
  * @param schema Record of string- or numeric-keyed property guards.
831
857
  * @param options When `{ exact: true }`, disallows own enumerable string-key
832
858
  * properties not in `schema`.
833
859
  * @returns Predicate that narrows to the inferred struct type.
834
- * @throws {TypeError} If `schema` has own symbol-keyed fields.
860
+ * @throws {TypeError} If `schema` has symbol-keyed, non-enumerable, or inherited
861
+ * string-keyed fields.
835
862
  */
836
863
  export declare function struct<const S extends SchemaShape<S>>(schema: StructSchemaShape<S>, options?: StructOptions): Predicate<InferSchema<S>>;
837
864
  //#endregion
package/dist/index.d.ts CHANGED
@@ -739,6 +739,22 @@ type MatchingDiscriminantMember<T extends object, K extends DiscriminantKey<T>,
739
739
  type DiscriminatedUnionGuardMap<T extends object, K extends DiscriminantKey<T>, Values extends DiscriminantValue> = { readonly [Value in Values as DiscriminantMapKey<Value>]: Predicate<MatchingDiscriminantMember<T, K, Value>>; };
740
740
  type InvalidGuardDiscriminantValues<K extends PropertyKey, Values extends DiscriminantValue, G extends object> = { [Value in Values as DiscriminantMapKey<Value>]: G extends Record<DiscriminantMapKey<Value>, infer Guard> ? GuardedOf<Guard> extends Record<K, DiscriminantValue> ? Value extends GuardedOf<Guard>[K] ? never : Value : Value : Value; }[DiscriminantMapKey<Values>];
741
741
  type GuardsMatchDiscriminantValues<K extends PropertyKey, Values extends DiscriminantValue, G extends object> = [InvalidGuardDiscriminantValues<K, Values, G>] extends [never] ? unknown : never;
742
+ type FallbackDiscriminant<Values extends DiscriminantValue, Value extends DiscriminantValue> = IsFiniteDiscriminantValue<Value> extends true ? IsUnion<Value> extends false ? DiscriminantRuntimeKey<Value> extends DiscriminantRuntimeKey<Values> ? never : unknown : never : never;
743
+ type RuntimePropertyKey<Key extends PropertyKey> = Key extends symbol ? Key : Key extends string | number ? `${Key}` : never;
744
+ type OmitRuntimeKey<Data extends object, Key extends PropertyKey> = { [Property in keyof Data as RuntimePropertyKey<Property> extends RuntimePropertyKey<Key> ? never : Property]: Data[Property]; };
745
+ type InvalidFallbackKey<Key extends PropertyKey> = Key extends unknown ? SinglePropertyKey<Key> extends never ? Key : never : never;
746
+ type InvalidFallbackData<Data extends object> = Data extends unknown ? [InvalidFallbackKey<keyof Data & PropertyKey>] extends [never] ? never : Data : never;
747
+ type FiniteFallbackData<Data extends object> = [InvalidFallbackData<Data>] extends [never] ? unknown : never;
748
+ type FallbackVariant<K extends PropertyKey, Value extends DiscriminantValue, Data extends Record<PropertyKey, unknown>> = Data extends unknown ? OmitRuntimeKey<Data, K> & Record<K, Value> : never;
749
+ type FallbackVariantConfig<Values extends DiscriminantValue, Value extends DiscriminantValue, Data extends Record<PropertyKey, unknown>> = {
750
+ readonly tag: Value & FallbackDiscriminant<Values, Value>;
751
+ readonly create: (this: void, input: unknown, discriminant: DiscriminantValue) => Data | undefined;
752
+ };
753
+ type Decoder<Output> = (input: unknown) => ParseResult<Output>;
754
+ declare const invalidFallbackClassifier: unique symbol;
755
+ type InvalidFallbackClassifier = {
756
+ readonly [invalidFallbackClassifier]: 'Fallback payloads must have finite property keys.';
757
+ };
742
758
  /**
743
759
  * Creates an exhaustive guard for a union whose members share a literal discriminant.
744
760
  * A tuple of every discriminant value keeps finite coverage explicit at runtime
@@ -752,6 +768,16 @@ type GuardsMatchDiscriminantValues<K extends PropertyKey, Values extends Discrim
752
768
  * @returns Predicate narrowing to the union accepted by the branch guards.
753
769
  */
754
770
  export declare function discriminatedUnion<T extends object>(): <const K extends DiscriminantKey<T>, const Values extends readonly DiscriminantValue[], const G extends DiscriminatedUnionGuardMap<T, K, Values[number]>>(discriminant: K, values: Values & ExactDiscriminantValues<T, K, Values>, guards: NoExtraKeys<G, DiscriminatedUnionGuardMap<T, K, Values[number]>> & NonCollidingDiscriminants<T, K> & GuardsMatchDiscriminantValues<K, Values[number], G>) => Predicate<GuardedOf<G[keyof G]>>;
771
+ /**
772
+ * Classifies a finite discriminated union and explicitly transforms undeclared values into one fallback variant.
773
+ * Known values remain exhaustive: a malformed known member fails instead of reaching the fallback.
774
+ * @param discriminant Required property that identifies each known union member.
775
+ * @param values Finite tuple containing every known discriminant value.
776
+ * @param guards Branch guards keyed by the known discriminant values.
777
+ * @param fallback Canonical fallback tag and receiver-free factory for an own non-function data-field payload; return `undefined` to reject the input.
778
+ * @returns Decoder that returns a guarded known member or fallback variant when valid.
779
+ */
780
+ export declare function discriminatedUnionWithFallback<T extends object>(): <const K extends DiscriminantKey<T>, const Values extends readonly DiscriminantValue[], const G extends DiscriminatedUnionGuardMap<T, K, Values[number]>, const FallbackValue extends DiscriminantValue, const FallbackData extends Record<PropertyKey, unknown>>(discriminant: K & SinglePropertyKey<K>, values: Values & ExactDiscriminantValues<T, K, Values>, guards: NoExtraKeys<G, DiscriminatedUnionGuardMap<T, K, Values[number]>> & NonCollidingDiscriminants<T, K> & GuardsMatchDiscriminantValues<K, Values[number], G>, fallback: FallbackVariantConfig<Values[number], FallbackValue, FallbackData>) => FiniteFallbackData<FallbackData> extends never ? InvalidFallbackClassifier : Decoder<GuardedOf<G[keyof G]> | FallbackVariant<K, FallbackValue, FallbackData>>;
755
781
  //#endregion
756
782
  //#region src/core/combinators/map.d.ts
757
783
  /**
@@ -822,16 +848,17 @@ export declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Pr
822
848
  */
823
849
  export declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
824
850
  /**
825
- * Validates an object against a field-to-guard schema with string runtime keys.
826
- * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
827
- * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
828
- * rejects extra keys when `exact: true`.
851
+ * Validates an object against a field-to-guard schema with own enumerable string
852
+ * keys. Numeric schema keys are normalized to strings by JavaScript; symbol,
853
+ * non-enumerable, and inherited fields are not supported. Keys are required unless
854
+ * wrapped with `optionalKey`; optionally rejects extra keys when `exact: true`.
829
855
  *
830
856
  * @param schema Record of string- or numeric-keyed property guards.
831
857
  * @param options When `{ exact: true }`, disallows own enumerable string-key
832
858
  * properties not in `schema`.
833
859
  * @returns Predicate that narrows to the inferred struct type.
834
- * @throws {TypeError} If `schema` has own symbol-keyed fields.
860
+ * @throws {TypeError} If `schema` has symbol-keyed, non-enumerable, or inherited
861
+ * string-keyed fields.
835
862
  */
836
863
  export declare function struct<const S extends SchemaShape<S>>(schema: StructSchemaShape<S>, options?: StructOptions): Predicate<InferSchema<S>>;
837
864
  //#endregion
package/dist/index.js CHANGED
@@ -537,7 +537,6 @@ const isNotNil = (value) => value !== null && value !== void 0;
537
537
  const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
538
538
  //#endregion
539
539
  //#region src/utils/guard-collections.ts
540
- const arrayValues = Array.prototype.values;
541
540
  const mapEntries = Map.prototype.entries;
542
541
  const setValues = Set.prototype.values;
543
542
  const everyIterableValue = (values, predicate) => {
@@ -560,9 +559,13 @@ const everyKeyValueEntry = (entries, predicate) => {
560
559
  const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
561
560
  /**
562
561
  * Checks built-in Array data without invoking an instance-provided iterator.
563
- * WHY: An Array subclass or instance may override its public iterator and throw.
562
+ * WHY: Indexed reads preserve hole-as-undefined semantics while avoiding iterator
563
+ * allocation on this hot path. They also bypass iterator overrides on subclasses.
564
564
  */
565
- const everyBrandedArrayValue = (values, predicate) => everyIterableValue(arrayValues.call(values), predicate);
565
+ const everyBrandedArrayValue = (values, predicate) => {
566
+ for (let index = 0; index < values.length; index += 1) if (!predicate(values[index])) return false;
567
+ return true;
568
+ };
566
569
  /**
567
570
  * Checks whether a tuple matches the provided element predicates in order.
568
571
  *
@@ -645,8 +648,48 @@ function nonEmptyArrayOf(elementGuard) {
645
648
  }
646
649
  //#endregion
647
650
  //#region src/core/combinators/discriminated-union.ts
651
+ function defineFallbackClassifier(classifier) {
652
+ return classifier;
653
+ }
654
+ function createFallbackVariant(fallbackData, discriminant, tag) {
655
+ const fallbackVariant = {};
656
+ const discriminantKey = isSymbol(discriminant) ? discriminant : String(discriminant);
657
+ for (const key of Reflect.ownKeys(fallbackData)) {
658
+ if (key === discriminantKey) continue;
659
+ const descriptor = Object.getOwnPropertyDescriptor(fallbackData, key);
660
+ if (descriptor !== void 0) Object.defineProperty(fallbackVariant, key, descriptor);
661
+ }
662
+ Object.defineProperty(fallbackVariant, discriminantKey, {
663
+ configurable: true,
664
+ enumerable: true,
665
+ value: tag,
666
+ writable: true
667
+ });
668
+ return fallbackVariant;
669
+ }
648
670
  const isDiscriminantValue = (value) => isString(value) || isNumberPrimitive(value) || isSymbol(value) || isBoolean(value);
671
+ const isFallbackDataDescriptor = (descriptor) => descriptor !== void 0 && "value" in descriptor && !isFunction(descriptor.value);
672
+ const isFallbackPayload = (value) => {
673
+ if (!isPlainObject(value)) return false;
674
+ const prototype = Object.getPrototypeOf(value);
675
+ if (prototype !== null && prototype !== Object.prototype) return false;
676
+ for (const key of Reflect.ownKeys(value)) {
677
+ const descriptor = Object.getOwnPropertyDescriptor(value, key);
678
+ if (!isFallbackDataDescriptor(descriptor)) return false;
679
+ }
680
+ return true;
681
+ };
649
682
  const toRuntimeKey = (value) => isSymbol(value) ? value : String(value);
683
+ const assertSafeFallbackTag = (values, tag) => {
684
+ if (!isDiscriminantValue(tag)) throw new TypeError("discriminatedUnion fallback tag must be a string, number, symbol, or boolean.");
685
+ const fallbackKey = toRuntimeKey(tag);
686
+ if (values.some((value) => toRuntimeKey(value) === fallbackKey)) throw new TypeError(`Fallback discriminatedUnion tag collides with a branch value: ${String(tag)}.`);
687
+ };
688
+ const getOwnDiscriminantValue = (input, discriminant) => {
689
+ if (!isObject(input) && !isFunction(input) || !hasOwnPropertyKey(input, discriminant)) return;
690
+ const value = Reflect.get(input, discriminant);
691
+ return isDiscriminantValue(value) ? value : void 0;
692
+ };
650
693
  const assertSafeProtoBranch = (values, guards) => {
651
694
  if (!values.includes("__proto__")) return;
652
695
  if (hasOwnPropertyKey(guards, "__proto__")) return;
@@ -679,9 +722,8 @@ function discriminatedUnion() {
679
722
  assertSafeProtoBranch(values, guards);
680
723
  const declaredKeys = assertBranchKeys(values, guards);
681
724
  return define((input) => {
682
- if (!isObject(input) && !isFunction(input) || !hasOwnPropertyKey(input, discriminant)) return false;
683
- const value = Reflect.get(input, discriminant);
684
- if (!isDiscriminantValue(value)) return false;
725
+ const value = getOwnDiscriminantValue(input, discriminant);
726
+ if (value === void 0) return false;
685
727
  const key = toRuntimeKey(value);
686
728
  if (!declaredKeys.has(key) || !hasOwnPropertyKey(guards, key)) return false;
687
729
  const guard = guards[key];
@@ -689,6 +731,44 @@ function discriminatedUnion() {
689
731
  });
690
732
  };
691
733
  }
734
+ /**
735
+ * Classifies a finite discriminated union and explicitly transforms undeclared values into one fallback variant.
736
+ * Known values remain exhaustive: a malformed known member fails instead of reaching the fallback.
737
+ * @param discriminant Required property that identifies each known union member.
738
+ * @param values Finite tuple containing every known discriminant value.
739
+ * @param guards Branch guards keyed by the known discriminant values.
740
+ * @param fallback Canonical fallback tag and receiver-free factory for an own non-function data-field payload; return `undefined` to reject the input.
741
+ * @returns Decoder that returns a guarded known member or fallback variant when valid.
742
+ */
743
+ function discriminatedUnionWithFallback() {
744
+ return (discriminant, values, guards, fallback) => {
745
+ assertSafeProtoBranch(values, guards);
746
+ const fallbackTag = fallback.tag;
747
+ const createFallback = fallback.create;
748
+ assertSafeFallbackTag(values, fallbackTag);
749
+ assertBranchKeys(values, guards);
750
+ const declaredValues = new Set(values);
751
+ return defineFallbackClassifier((input) => {
752
+ const value = getOwnDiscriminantValue(input, discriminant);
753
+ if (value === void 0) return { valid: false };
754
+ if (!declaredValues.has(value)) {
755
+ const fallbackData = createFallback(input, value);
756
+ if (fallbackData === void 0 || !isFallbackPayload(fallbackData)) return { valid: false };
757
+ return {
758
+ valid: true,
759
+ value: createFallbackVariant(fallbackData, discriminant, fallbackTag)
760
+ };
761
+ }
762
+ const key = toRuntimeKey(value);
763
+ if (!hasOwnPropertyKey(guards, key)) return { valid: false };
764
+ const guard = guards[key];
765
+ return guard(input) ? {
766
+ valid: true,
767
+ value: input
768
+ } : { valid: false };
769
+ });
770
+ };
771
+ }
692
772
  //#endregion
693
773
  //#region src/core/combinators/map.ts
694
774
  /**
@@ -761,6 +841,36 @@ function setOf(valueGuard) {
761
841
  }
762
842
  //#endregion
763
843
  //#region src/core/combinators/struct.ts
844
+ const OBJECT_CONSTRUCTOR_SOURCE = Function.prototype.toString.call(Object);
845
+ const isObjectPrototype = (prototype) => {
846
+ const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
847
+ return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === OBJECT_CONSTRUCTOR_SOURCE;
848
+ };
849
+ const hasOnlyEnumerableOwnStringKeys = (schema) => Object.getOwnPropertyNames(schema).every((key) => Object.prototype.propertyIsEnumerable.call(schema, key));
850
+ const hasInheritedStringKeys = (schema) => {
851
+ let prototype = Object.getPrototypeOf(schema);
852
+ while (prototype !== null && !isObjectPrototype(prototype)) {
853
+ if (Object.getOwnPropertyNames(prototype).some((key) => {
854
+ if (key !== "constructor") return true;
855
+ const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
856
+ return !(typeof descriptor?.value === "function" && descriptor.value.prototype === prototype);
857
+ })) return true;
858
+ prototype = Object.getPrototypeOf(prototype);
859
+ }
860
+ return false;
861
+ };
862
+ const hasInheritedSymbolKeys = (schema) => {
863
+ let prototype = Object.getPrototypeOf(schema);
864
+ while (prototype !== null && !isObjectPrototype(prototype)) {
865
+ if (Object.getOwnPropertySymbols(prototype).length > 0) return true;
866
+ prototype = Object.getPrototypeOf(prototype);
867
+ }
868
+ return false;
869
+ };
870
+ const assertValidSchemaKeys = (schema) => {
871
+ if (Object.getOwnPropertySymbols(schema).length > 0 || hasInheritedSymbolKeys(schema)) throw new TypeError("struct schema fields cannot use symbol keys");
872
+ if (!hasOnlyEnumerableOwnStringKeys(schema) || hasInheritedStringKeys(schema)) throw new TypeError("struct schema fields must be own enumerable string keys");
873
+ };
764
874
  const isOptionalSchemaField = define((field) => isObject(field) && field.optional === true && isFunction(field.guard));
765
875
  const hasRequiredKeys = (obj, entries) => entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]));
766
876
  const hasValidOptionalKeys = (obj, entries) => entries.every(([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key]));
@@ -785,23 +895,24 @@ function optionalKey(guard) {
785
895
  };
786
896
  }
787
897
  /**
788
- * Validates an object against a field-to-guard schema with string runtime keys.
789
- * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
790
- * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
791
- * rejects extra keys when `exact: true`.
898
+ * Validates an object against a field-to-guard schema with own enumerable string
899
+ * keys. Numeric schema keys are normalized to strings by JavaScript; symbol,
900
+ * non-enumerable, and inherited fields are not supported. Keys are required unless
901
+ * wrapped with `optionalKey`; optionally rejects extra keys when `exact: true`.
792
902
  *
793
903
  * @param schema Record of string- or numeric-keyed property guards.
794
904
  * @param options When `{ exact: true }`, disallows own enumerable string-key
795
905
  * properties not in `schema`.
796
906
  * @returns Predicate that narrows to the inferred struct type.
797
- * @throws {TypeError} If `schema` has own symbol-keyed fields.
907
+ * @throws {TypeError} If `schema` has symbol-keyed, non-enumerable, or inherited
908
+ * string-keyed fields.
798
909
  */
799
910
  function struct(schema, options) {
800
911
  return createStruct(schema, options);
801
912
  }
802
913
  /** @internal Shared implementation for string-keyed schema builders. */
803
914
  function createStruct(schema, options) {
804
- if (Object.getOwnPropertySymbols(schema).length > 0) throw new TypeError("struct schema fields cannot use symbol keys");
915
+ assertValidSchemaKeys(schema);
805
916
  const requiredEntries = [];
806
917
  const optionalEntries = [];
807
918
  const schemaKeys = [];
@@ -873,6 +984,7 @@ exports.arrayOf = arrayOf;
873
984
  exports.assert = assert;
874
985
  exports.define = define;
875
986
  exports.discriminatedUnion = discriminatedUnion;
987
+ exports.discriminatedUnionWithFallback = discriminatedUnionWithFallback;
876
988
  exports.equals = equals;
877
989
  exports.equalsBy = equalsBy;
878
990
  exports.equalsKey = equalsKey;
package/dist/index.mjs CHANGED
@@ -536,7 +536,6 @@ const isNotNil = (value) => value !== null && value !== void 0;
536
536
  const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
537
537
  //#endregion
538
538
  //#region src/utils/guard-collections.ts
539
- const arrayValues = Array.prototype.values;
540
539
  const mapEntries = Map.prototype.entries;
541
540
  const setValues = Set.prototype.values;
542
541
  const everyIterableValue = (values, predicate) => {
@@ -559,9 +558,13 @@ const everyKeyValueEntry = (entries, predicate) => {
559
558
  const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
560
559
  /**
561
560
  * Checks built-in Array data without invoking an instance-provided iterator.
562
- * WHY: An Array subclass or instance may override its public iterator and throw.
561
+ * WHY: Indexed reads preserve hole-as-undefined semantics while avoiding iterator
562
+ * allocation on this hot path. They also bypass iterator overrides on subclasses.
563
563
  */
564
- const everyBrandedArrayValue = (values, predicate) => everyIterableValue(arrayValues.call(values), predicate);
564
+ const everyBrandedArrayValue = (values, predicate) => {
565
+ for (let index = 0; index < values.length; index += 1) if (!predicate(values[index])) return false;
566
+ return true;
567
+ };
565
568
  /**
566
569
  * Checks whether a tuple matches the provided element predicates in order.
567
570
  *
@@ -644,8 +647,48 @@ function nonEmptyArrayOf(elementGuard) {
644
647
  }
645
648
  //#endregion
646
649
  //#region src/core/combinators/discriminated-union.ts
650
+ function defineFallbackClassifier(classifier) {
651
+ return classifier;
652
+ }
653
+ function createFallbackVariant(fallbackData, discriminant, tag) {
654
+ const fallbackVariant = {};
655
+ const discriminantKey = isSymbol(discriminant) ? discriminant : String(discriminant);
656
+ for (const key of Reflect.ownKeys(fallbackData)) {
657
+ if (key === discriminantKey) continue;
658
+ const descriptor = Object.getOwnPropertyDescriptor(fallbackData, key);
659
+ if (descriptor !== void 0) Object.defineProperty(fallbackVariant, key, descriptor);
660
+ }
661
+ Object.defineProperty(fallbackVariant, discriminantKey, {
662
+ configurable: true,
663
+ enumerable: true,
664
+ value: tag,
665
+ writable: true
666
+ });
667
+ return fallbackVariant;
668
+ }
647
669
  const isDiscriminantValue = (value) => isString(value) || isNumberPrimitive(value) || isSymbol(value) || isBoolean(value);
670
+ const isFallbackDataDescriptor = (descriptor) => descriptor !== void 0 && "value" in descriptor && !isFunction(descriptor.value);
671
+ const isFallbackPayload = (value) => {
672
+ if (!isPlainObject(value)) return false;
673
+ const prototype = Object.getPrototypeOf(value);
674
+ if (prototype !== null && prototype !== Object.prototype) return false;
675
+ for (const key of Reflect.ownKeys(value)) {
676
+ const descriptor = Object.getOwnPropertyDescriptor(value, key);
677
+ if (!isFallbackDataDescriptor(descriptor)) return false;
678
+ }
679
+ return true;
680
+ };
648
681
  const toRuntimeKey = (value) => isSymbol(value) ? value : String(value);
682
+ const assertSafeFallbackTag = (values, tag) => {
683
+ if (!isDiscriminantValue(tag)) throw new TypeError("discriminatedUnion fallback tag must be a string, number, symbol, or boolean.");
684
+ const fallbackKey = toRuntimeKey(tag);
685
+ if (values.some((value) => toRuntimeKey(value) === fallbackKey)) throw new TypeError(`Fallback discriminatedUnion tag collides with a branch value: ${String(tag)}.`);
686
+ };
687
+ const getOwnDiscriminantValue = (input, discriminant) => {
688
+ if (!isObject(input) && !isFunction(input) || !hasOwnPropertyKey(input, discriminant)) return;
689
+ const value = Reflect.get(input, discriminant);
690
+ return isDiscriminantValue(value) ? value : void 0;
691
+ };
649
692
  const assertSafeProtoBranch = (values, guards) => {
650
693
  if (!values.includes("__proto__")) return;
651
694
  if (hasOwnPropertyKey(guards, "__proto__")) return;
@@ -678,9 +721,8 @@ function discriminatedUnion() {
678
721
  assertSafeProtoBranch(values, guards);
679
722
  const declaredKeys = assertBranchKeys(values, guards);
680
723
  return define((input) => {
681
- if (!isObject(input) && !isFunction(input) || !hasOwnPropertyKey(input, discriminant)) return false;
682
- const value = Reflect.get(input, discriminant);
683
- if (!isDiscriminantValue(value)) return false;
724
+ const value = getOwnDiscriminantValue(input, discriminant);
725
+ if (value === void 0) return false;
684
726
  const key = toRuntimeKey(value);
685
727
  if (!declaredKeys.has(key) || !hasOwnPropertyKey(guards, key)) return false;
686
728
  const guard = guards[key];
@@ -688,6 +730,44 @@ function discriminatedUnion() {
688
730
  });
689
731
  };
690
732
  }
733
+ /**
734
+ * Classifies a finite discriminated union and explicitly transforms undeclared values into one fallback variant.
735
+ * Known values remain exhaustive: a malformed known member fails instead of reaching the fallback.
736
+ * @param discriminant Required property that identifies each known union member.
737
+ * @param values Finite tuple containing every known discriminant value.
738
+ * @param guards Branch guards keyed by the known discriminant values.
739
+ * @param fallback Canonical fallback tag and receiver-free factory for an own non-function data-field payload; return `undefined` to reject the input.
740
+ * @returns Decoder that returns a guarded known member or fallback variant when valid.
741
+ */
742
+ function discriminatedUnionWithFallback() {
743
+ return (discriminant, values, guards, fallback) => {
744
+ assertSafeProtoBranch(values, guards);
745
+ const fallbackTag = fallback.tag;
746
+ const createFallback = fallback.create;
747
+ assertSafeFallbackTag(values, fallbackTag);
748
+ assertBranchKeys(values, guards);
749
+ const declaredValues = new Set(values);
750
+ return defineFallbackClassifier((input) => {
751
+ const value = getOwnDiscriminantValue(input, discriminant);
752
+ if (value === void 0) return { valid: false };
753
+ if (!declaredValues.has(value)) {
754
+ const fallbackData = createFallback(input, value);
755
+ if (fallbackData === void 0 || !isFallbackPayload(fallbackData)) return { valid: false };
756
+ return {
757
+ valid: true,
758
+ value: createFallbackVariant(fallbackData, discriminant, fallbackTag)
759
+ };
760
+ }
761
+ const key = toRuntimeKey(value);
762
+ if (!hasOwnPropertyKey(guards, key)) return { valid: false };
763
+ const guard = guards[key];
764
+ return guard(input) ? {
765
+ valid: true,
766
+ value: input
767
+ } : { valid: false };
768
+ });
769
+ };
770
+ }
691
771
  //#endregion
692
772
  //#region src/core/combinators/map.ts
693
773
  /**
@@ -760,6 +840,36 @@ function setOf(valueGuard) {
760
840
  }
761
841
  //#endregion
762
842
  //#region src/core/combinators/struct.ts
843
+ const OBJECT_CONSTRUCTOR_SOURCE = Function.prototype.toString.call(Object);
844
+ const isObjectPrototype = (prototype) => {
845
+ const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
846
+ return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === OBJECT_CONSTRUCTOR_SOURCE;
847
+ };
848
+ const hasOnlyEnumerableOwnStringKeys = (schema) => Object.getOwnPropertyNames(schema).every((key) => Object.prototype.propertyIsEnumerable.call(schema, key));
849
+ const hasInheritedStringKeys = (schema) => {
850
+ let prototype = Object.getPrototypeOf(schema);
851
+ while (prototype !== null && !isObjectPrototype(prototype)) {
852
+ if (Object.getOwnPropertyNames(prototype).some((key) => {
853
+ if (key !== "constructor") return true;
854
+ const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
855
+ return !(typeof descriptor?.value === "function" && descriptor.value.prototype === prototype);
856
+ })) return true;
857
+ prototype = Object.getPrototypeOf(prototype);
858
+ }
859
+ return false;
860
+ };
861
+ const hasInheritedSymbolKeys = (schema) => {
862
+ let prototype = Object.getPrototypeOf(schema);
863
+ while (prototype !== null && !isObjectPrototype(prototype)) {
864
+ if (Object.getOwnPropertySymbols(prototype).length > 0) return true;
865
+ prototype = Object.getPrototypeOf(prototype);
866
+ }
867
+ return false;
868
+ };
869
+ const assertValidSchemaKeys = (schema) => {
870
+ if (Object.getOwnPropertySymbols(schema).length > 0 || hasInheritedSymbolKeys(schema)) throw new TypeError("struct schema fields cannot use symbol keys");
871
+ if (!hasOnlyEnumerableOwnStringKeys(schema) || hasInheritedStringKeys(schema)) throw new TypeError("struct schema fields must be own enumerable string keys");
872
+ };
763
873
  const isOptionalSchemaField = define((field) => isObject(field) && field.optional === true && isFunction(field.guard));
764
874
  const hasRequiredKeys = (obj, entries) => entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]));
765
875
  const hasValidOptionalKeys = (obj, entries) => entries.every(([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key]));
@@ -784,23 +894,24 @@ function optionalKey(guard) {
784
894
  };
785
895
  }
786
896
  /**
787
- * Validates an object against a field-to-guard schema with string runtime keys.
788
- * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
789
- * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
790
- * rejects extra keys when `exact: true`.
897
+ * Validates an object against a field-to-guard schema with own enumerable string
898
+ * keys. Numeric schema keys are normalized to strings by JavaScript; symbol,
899
+ * non-enumerable, and inherited fields are not supported. Keys are required unless
900
+ * wrapped with `optionalKey`; optionally rejects extra keys when `exact: true`.
791
901
  *
792
902
  * @param schema Record of string- or numeric-keyed property guards.
793
903
  * @param options When `{ exact: true }`, disallows own enumerable string-key
794
904
  * properties not in `schema`.
795
905
  * @returns Predicate that narrows to the inferred struct type.
796
- * @throws {TypeError} If `schema` has own symbol-keyed fields.
906
+ * @throws {TypeError} If `schema` has symbol-keyed, non-enumerable, or inherited
907
+ * string-keyed fields.
797
908
  */
798
909
  function struct(schema, options) {
799
910
  return createStruct(schema, options);
800
911
  }
801
912
  /** @internal Shared implementation for string-keyed schema builders. */
802
913
  function createStruct(schema, options) {
803
- if (Object.getOwnPropertySymbols(schema).length > 0) throw new TypeError("struct schema fields cannot use symbol keys");
914
+ assertValidSchemaKeys(schema);
804
915
  const requiredEntries = [];
805
916
  const optionalEntries = [];
806
917
  const schemaKeys = [];
@@ -866,4 +977,4 @@ function tupleOf(...guards) {
866
977
  */
867
978
  const toBooleanPredicates = (predicates) => predicates;
868
979
  //#endregion
869
- export { and, andAll, arrayOf, assert, define, discriminatedUnion, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNotNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, refineDefinedKey, refineIndex, refineKey, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
980
+ export { and, andAll, arrayOf, assert, define, discriminatedUnion, discriminatedUnionWithFallback, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNotNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, refineDefinedKey, refineIndex, refineKey, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.15.3",
3
+ "version": "1.16.0",
4
4
  "description": "Zero-dependency TypeScript runtime validation toolkit for composable type guards and natural type narrowing.",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -22,6 +22,7 @@
22
22
  "test:package": "node tests/package-smoke.mjs",
23
23
  "test:package:vlt": "node tests/vlt-package-smoke.mjs",
24
24
  "bench:core": "node bench/core-workloads.mjs",
25
+ "bench:array-traversal": "node bench/array-traversal.mjs",
25
26
  "lint": "oxlint .",
26
27
  "format": "oxfmt .",
27
28
  "format:check": "oxfmt --check .",
@@ -59,6 +60,9 @@
59
60
  "homepage": "https://is-kit.dev/",
60
61
  "author": "nyaomaru",
61
62
  "license": "MIT",
63
+ "engines": {
64
+ "node": ">=22"
65
+ },
62
66
  "packageManager": "pnpm@11.2.2",
63
67
  "devDependencies": {
64
68
  "@types/jest": "^30.0.0",