is-kit 1.15.1 → 1.15.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.d.mts CHANGED
@@ -64,6 +64,14 @@ type StructOptions = Readonly<{
64
64
  * Object schema shape preserving concrete keys.
65
65
  */
66
66
  type SchemaShape<S extends object> = Readonly<{ [K in keyof S]: SchemaField; }>;
67
+ /**
68
+ * Schema shape accepted by `struct`, limited to JavaScript string and numeric keys.
69
+ *
70
+ * Numeric keys are included because JavaScript normalizes them to string property
71
+ * keys during enumeration. Symbol keys are excluded because `struct` does not
72
+ * enumerate them at runtime.
73
+ */
74
+ type StructSchemaShape<S extends SchemaShape<S>> = Extract<keyof S, symbol> extends never ? S : never;
67
75
  type Simplify<T> = { [K in keyof T]: T[K]; };
68
76
  type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
69
77
  type RequiredSchemaKeys<S extends SchemaShape<S>> = { [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K; }[keyof S];
@@ -666,9 +674,10 @@ export declare const isDataView: Guard$1<DataView<ArrayBufferLike>>;
666
674
  */
667
675
  export declare const isTypedArray: Predicate<ArrayBufferView<ArrayBufferLike>>;
668
676
  /**
669
- * Checks whether a value is an `Error` (instance of Error or plain Error object tag).
677
+ * Checks whether a value is an `Error`.
670
678
  *
671
679
  * @returns Predicate narrowing to `Error`.
680
+ * @see https://github.com/nyaomaru/is-kit/issues/325
672
681
  */
673
682
  export declare const isError: Predicate<Error>;
674
683
  /**
@@ -779,14 +788,18 @@ export declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(va
779
788
  export declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...valuesOrArray: T | [T]): Predicate<T[number]>;
780
789
  //#endregion
781
790
  //#region src/core/combinators/record.d.ts
791
+ type RecordOfResult<K extends string, V> = string extends K ? Readonly<Record<string, V>> : Readonly<Partial<Record<K, V>>>;
782
792
  /**
783
793
  * Validates a record-like object by guarding both keys and values.
784
794
  *
785
- * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
795
+ * The key guard restricts which string keys may be present; it does not require
796
+ * every key represented by the guarded key type.
797
+ *
798
+ * @param keyFunction Guard for string keys (for example, a literal-key pattern).
786
799
  * @param valueFunction Guard applied to each value in the record.
787
800
  * @returns Predicate narrowing to a readonly record with guarded key/value types.
788
801
  */
789
- export declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
802
+ export declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<RecordOfResult<GuardedOf<KF>, GuardedOf<VF>>>;
790
803
  //#endregion
791
804
  //#region src/core/combinators/set.d.ts
792
805
  /**
@@ -809,16 +822,18 @@ export declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Pr
809
822
  */
810
823
  export declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
811
824
  /**
812
- * Validates an object against a field-to-guard schema.
813
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
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
814
828
  * rejects extra keys when `exact: true`.
815
829
  *
816
- * @param schema Record of property guards.
830
+ * @param schema Record of string- or numeric-keyed property guards.
817
831
  * @param options When `{ exact: true }`, disallows own enumerable string-key
818
832
  * properties not in `schema`.
819
833
  * @returns Predicate that narrows to the inferred struct type.
834
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
820
835
  */
821
- export declare function struct<const S extends SchemaShape<S>>(schema: S, options?: StructOptions): Predicate<InferSchema<S>>;
836
+ export declare function struct<const S extends SchemaShape<S>>(schema: StructSchemaShape<S>, options?: StructOptions): Predicate<InferSchema<S>>;
822
837
  //#endregion
823
838
  //#region src/core/combinators/typed-struct.d.ts
824
839
  /**
package/dist/index.d.ts CHANGED
@@ -64,6 +64,14 @@ type StructOptions = Readonly<{
64
64
  * Object schema shape preserving concrete keys.
65
65
  */
66
66
  type SchemaShape<S extends object> = Readonly<{ [K in keyof S]: SchemaField; }>;
67
+ /**
68
+ * Schema shape accepted by `struct`, limited to JavaScript string and numeric keys.
69
+ *
70
+ * Numeric keys are included because JavaScript normalizes them to string property
71
+ * keys during enumeration. Symbol keys are excluded because `struct` does not
72
+ * enumerate them at runtime.
73
+ */
74
+ type StructSchemaShape<S extends SchemaShape<S>> = Extract<keyof S, symbol> extends never ? S : never;
67
75
  type Simplify<T> = { [K in keyof T]: T[K]; };
68
76
  type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
69
77
  type RequiredSchemaKeys<S extends SchemaShape<S>> = { [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K; }[keyof S];
@@ -666,9 +674,10 @@ export declare const isDataView: Guard$1<DataView<ArrayBufferLike>>;
666
674
  */
667
675
  export declare const isTypedArray: Predicate<ArrayBufferView<ArrayBufferLike>>;
668
676
  /**
669
- * Checks whether a value is an `Error` (instance of Error or plain Error object tag).
677
+ * Checks whether a value is an `Error`.
670
678
  *
671
679
  * @returns Predicate narrowing to `Error`.
680
+ * @see https://github.com/nyaomaru/is-kit/issues/325
672
681
  */
673
682
  export declare const isError: Predicate<Error>;
674
683
  /**
@@ -779,14 +788,18 @@ export declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(va
779
788
  export declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...valuesOrArray: T | [T]): Predicate<T[number]>;
780
789
  //#endregion
781
790
  //#region src/core/combinators/record.d.ts
791
+ type RecordOfResult<K extends string, V> = string extends K ? Readonly<Record<string, V>> : Readonly<Partial<Record<K, V>>>;
782
792
  /**
783
793
  * Validates a record-like object by guarding both keys and values.
784
794
  *
785
- * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
795
+ * The key guard restricts which string keys may be present; it does not require
796
+ * every key represented by the guarded key type.
797
+ *
798
+ * @param keyFunction Guard for string keys (for example, a literal-key pattern).
786
799
  * @param valueFunction Guard applied to each value in the record.
787
800
  * @returns Predicate narrowing to a readonly record with guarded key/value types.
788
801
  */
789
- export declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
802
+ export declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<RecordOfResult<GuardedOf<KF>, GuardedOf<VF>>>;
790
803
  //#endregion
791
804
  //#region src/core/combinators/set.d.ts
792
805
  /**
@@ -809,16 +822,18 @@ export declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Pr
809
822
  */
810
823
  export declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
811
824
  /**
812
- * Validates an object against a field-to-guard schema.
813
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
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
814
828
  * rejects extra keys when `exact: true`.
815
829
  *
816
- * @param schema Record of property guards.
830
+ * @param schema Record of string- or numeric-keyed property guards.
817
831
  * @param options When `{ exact: true }`, disallows own enumerable string-key
818
832
  * properties not in `schema`.
819
833
  * @returns Predicate that narrows to the inferred struct type.
834
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
820
835
  */
821
- export declare function struct<const S extends SchemaShape<S>>(schema: S, options?: StructOptions): Predicate<InferSchema<S>>;
836
+ export declare function struct<const S extends SchemaShape<S>>(schema: StructSchemaShape<S>, options?: StructOptions): Predicate<InferSchema<S>>;
822
837
  //#endregion
823
838
  //#region src/core/combinators/typed-struct.d.ts
824
839
  /**
package/dist/index.js CHANGED
@@ -41,6 +41,7 @@ const getTag = (value) => objectToString.call(value);
41
41
  //#endregion
42
42
  //#region src/core/object.ts
43
43
  const BUILTIN_BRAND_SENTINEL = Object.freeze({});
44
+ const nativeIsError = Error.isError;
44
45
  const getIntrinsicGetter = (prototype, key) => {
45
46
  return Object.getOwnPropertyDescriptor(prototype, key)?.get ?? (() => {
46
47
  throw new TypeError(`Missing intrinsic getter: ${String(key)}`);
@@ -175,11 +176,18 @@ const isDataView = defineIntrinsicBrandGuard((value) => dataViewBuffer.call(valu
175
176
  */
176
177
  const isTypedArray = define((value) => typedArrayName?.call(value) !== void 0);
177
178
  /**
178
- * Checks whether a value is an `Error` (instance of Error or plain Error object tag).
179
+ * Checks whether a value is an `Error`.
179
180
  *
180
181
  * @returns Predicate narrowing to `Error`.
182
+ * @see https://github.com/nyaomaru/is-kit/issues/325
181
183
  */
182
- const isError = define((value) => value instanceof Error || getTag(value) === "[object Error]");
184
+ const isError = define((value) => {
185
+ try {
186
+ return typeof nativeIsError === "function" ? nativeIsError(value) : value instanceof Error || getTag(value) === "[object Error]";
187
+ } catch {
188
+ return false;
189
+ }
190
+ });
183
191
  /**
184
192
  * Checks whether a value is a `URL` (in environments with URL available).
185
193
  *
@@ -730,7 +738,10 @@ function oneOfValues(...args) {
730
738
  /**
731
739
  * Validates a record-like object by guarding both keys and values.
732
740
  *
733
- * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
741
+ * The key guard restricts which string keys may be present; it does not require
742
+ * every key represented by the guarded key type.
743
+ *
744
+ * @param keyFunction Guard for string keys (for example, a literal-key pattern).
734
745
  * @param valueFunction Guard applied to each value in the record.
735
746
  * @returns Predicate narrowing to a readonly record with guarded key/value types.
736
747
  */
@@ -754,6 +765,10 @@ const isOptionalSchemaField = define((field) => isObject(field) && field.optiona
754
765
  const hasRequiredKeys = (obj, entries) => entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]));
755
766
  const hasValidOptionalKeys = (obj, entries) => entries.every(([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key]));
756
767
  const hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
768
+ const hasOnlyRequiredKeys = (obj, schemaKeys, allowed) => {
769
+ const keys = Object.keys(obj);
770
+ return keys.length <= schemaKeys.length && keys.every((key, index) => key === schemaKeys[index] || allowed.has(key));
771
+ };
757
772
  /**
758
773
  * Marks a struct schema field as optional at the key level.
759
774
  *
@@ -770,16 +785,23 @@ function optionalKey(guard) {
770
785
  };
771
786
  }
772
787
  /**
773
- * Validates an object against a field-to-guard schema.
774
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
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
775
791
  * rejects extra keys when `exact: true`.
776
792
  *
777
- * @param schema Record of property guards.
793
+ * @param schema Record of string- or numeric-keyed property guards.
778
794
  * @param options When `{ exact: true }`, disallows own enumerable string-key
779
795
  * properties not in `schema`.
780
796
  * @returns Predicate that narrows to the inferred struct type.
797
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
781
798
  */
782
799
  function struct(schema, options) {
800
+ return createStruct(schema, options);
801
+ }
802
+ /** @internal Shared implementation for string-keyed schema builders. */
803
+ function createStruct(schema, options) {
804
+ if (Object.getOwnPropertySymbols(schema).length > 0) throw new TypeError("struct schema fields cannot use symbol keys");
783
805
  const requiredEntries = [];
784
806
  const optionalEntries = [];
785
807
  const schemaKeys = [];
@@ -794,10 +816,12 @@ function struct(schema, options) {
794
816
  requiredEntries.push([key, field]);
795
817
  }
796
818
  const allowed = options?.exact ? new Set(schemaKeys) : null;
819
+ const requiredOnly = optionalEntries.length === 0;
797
820
  return define((input) => {
798
821
  if (!isPlainObject(input)) return false;
799
822
  const obj = input;
800
823
  if (!hasRequiredKeys(obj, requiredEntries)) return false;
824
+ if (allowed && requiredOnly) return hasOnlyRequiredKeys(obj, schemaKeys, allowed);
801
825
  if (!hasValidOptionalKeys(obj, optionalEntries)) return false;
802
826
  if (!allowed) return true;
803
827
  return hasOnlyAllowedKeys(obj, allowed);
@@ -818,7 +842,7 @@ function struct(schema, options) {
818
842
  * @returns Builder that rejects missing, extra, or incompatible struct fields.
819
843
  */
820
844
  function typedStruct() {
821
- return (fields, options) => struct(fields, options);
845
+ return (fields, options) => createStruct(fields, options);
822
846
  }
823
847
  //#endregion
824
848
  //#region src/core/combinators/tuple.ts
package/dist/index.mjs CHANGED
@@ -40,6 +40,7 @@ const getTag = (value) => objectToString.call(value);
40
40
  //#endregion
41
41
  //#region src/core/object.ts
42
42
  const BUILTIN_BRAND_SENTINEL = Object.freeze({});
43
+ const nativeIsError = Error.isError;
43
44
  const getIntrinsicGetter = (prototype, key) => {
44
45
  return Object.getOwnPropertyDescriptor(prototype, key)?.get ?? (() => {
45
46
  throw new TypeError(`Missing intrinsic getter: ${String(key)}`);
@@ -174,11 +175,18 @@ const isDataView = defineIntrinsicBrandGuard((value) => dataViewBuffer.call(valu
174
175
  */
175
176
  const isTypedArray = define((value) => typedArrayName?.call(value) !== void 0);
176
177
  /**
177
- * Checks whether a value is an `Error` (instance of Error or plain Error object tag).
178
+ * Checks whether a value is an `Error`.
178
179
  *
179
180
  * @returns Predicate narrowing to `Error`.
181
+ * @see https://github.com/nyaomaru/is-kit/issues/325
180
182
  */
181
- const isError = define((value) => value instanceof Error || getTag(value) === "[object Error]");
183
+ const isError = define((value) => {
184
+ try {
185
+ return typeof nativeIsError === "function" ? nativeIsError(value) : value instanceof Error || getTag(value) === "[object Error]";
186
+ } catch {
187
+ return false;
188
+ }
189
+ });
182
190
  /**
183
191
  * Checks whether a value is a `URL` (in environments with URL available).
184
192
  *
@@ -729,7 +737,10 @@ function oneOfValues(...args) {
729
737
  /**
730
738
  * Validates a record-like object by guarding both keys and values.
731
739
  *
732
- * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
740
+ * The key guard restricts which string keys may be present; it does not require
741
+ * every key represented by the guarded key type.
742
+ *
743
+ * @param keyFunction Guard for string keys (for example, a literal-key pattern).
733
744
  * @param valueFunction Guard applied to each value in the record.
734
745
  * @returns Predicate narrowing to a readonly record with guarded key/value types.
735
746
  */
@@ -753,6 +764,10 @@ const isOptionalSchemaField = define((field) => isObject(field) && field.optiona
753
764
  const hasRequiredKeys = (obj, entries) => entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]));
754
765
  const hasValidOptionalKeys = (obj, entries) => entries.every(([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key]));
755
766
  const hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
767
+ const hasOnlyRequiredKeys = (obj, schemaKeys, allowed) => {
768
+ const keys = Object.keys(obj);
769
+ return keys.length <= schemaKeys.length && keys.every((key, index) => key === schemaKeys[index] || allowed.has(key));
770
+ };
756
771
  /**
757
772
  * Marks a struct schema field as optional at the key level.
758
773
  *
@@ -769,16 +784,23 @@ function optionalKey(guard) {
769
784
  };
770
785
  }
771
786
  /**
772
- * Validates an object against a field-to-guard schema.
773
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
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
774
790
  * rejects extra keys when `exact: true`.
775
791
  *
776
- * @param schema Record of property guards.
792
+ * @param schema Record of string- or numeric-keyed property guards.
777
793
  * @param options When `{ exact: true }`, disallows own enumerable string-key
778
794
  * properties not in `schema`.
779
795
  * @returns Predicate that narrows to the inferred struct type.
796
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
780
797
  */
781
798
  function struct(schema, options) {
799
+ return createStruct(schema, options);
800
+ }
801
+ /** @internal Shared implementation for string-keyed schema builders. */
802
+ function createStruct(schema, options) {
803
+ if (Object.getOwnPropertySymbols(schema).length > 0) throw new TypeError("struct schema fields cannot use symbol keys");
782
804
  const requiredEntries = [];
783
805
  const optionalEntries = [];
784
806
  const schemaKeys = [];
@@ -793,10 +815,12 @@ function struct(schema, options) {
793
815
  requiredEntries.push([key, field]);
794
816
  }
795
817
  const allowed = options?.exact ? new Set(schemaKeys) : null;
818
+ const requiredOnly = optionalEntries.length === 0;
796
819
  return define((input) => {
797
820
  if (!isPlainObject(input)) return false;
798
821
  const obj = input;
799
822
  if (!hasRequiredKeys(obj, requiredEntries)) return false;
823
+ if (allowed && requiredOnly) return hasOnlyRequiredKeys(obj, schemaKeys, allowed);
800
824
  if (!hasValidOptionalKeys(obj, optionalEntries)) return false;
801
825
  if (!allowed) return true;
802
826
  return hasOnlyAllowedKeys(obj, allowed);
@@ -817,7 +841,7 @@ function struct(schema, options) {
817
841
  * @returns Builder that rejects missing, extra, or incompatible struct fields.
818
842
  */
819
843
  function typedStruct() {
820
- return (fields, options) => struct(fields, options);
844
+ return (fields, options) => createStruct(fields, options);
821
845
  }
822
846
  //#endregion
823
847
  //#region src/core/combinators/tuple.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.15.1",
3
+ "version": "1.15.3",
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",