is-kit 1.1.13 → 1.3.0

package/README.md

@@ -157,12 +157,31 @@ isInfiniteNumber(Infinity); // true
 isInfiniteNumber(1); // false
 ```
 
+### Object guards
+
+Object/built-in guards cover arrays, dates, maps/sets, and more. Use
+`isInstanceOf` when you want a reusable guard from a class constructor.
+
+```ts
+import { isArray, isDate, isInstanceOf } from 'is-kit';
+
+class Animal {}
+class Dog extends Animal {}
+
+const isAnimal = isInstanceOf(Animal);
+
+isArray([]); // true
+isDate(new Date()); // true
+isAnimal(new Dog()); // true
+isAnimal({}); // false
+```
+
 ## Core Ideas
 
 - **Define once**: `define<T>(fn)` turns a plain function into a type guard.
 - **Upgrade predicates**: `predicateToRefine(fn)` adds narrowing.
 - **Compose freely**: `and`, `or`, `not`, `oneOf`, `arrayOf`, `struct` …
-- **Stay ergonomic**: helpers like `nullable`, `optional`, `equals`, `safeParse`, `hasKey`, `narrowKeyTo`.
+- **Stay ergonomic**: helpers like `nullable`, `optional`, `equals`, `safeParse`, `assert`, `hasKey`, `narrowKeyTo`.
 
 ### Key Helpers
 

package/dist/index.d.mts

@@ -40,6 +40,17 @@ declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
  */
 declare const predicateToRefine: <A>(fn: (value: A) => boolean) => Refine<A, A>;
 
+/**
+ * Asserts that a value satisfies a guard or refinement, otherwise throws.
+ *
+ * @param guard Guard/refinement to evaluate.
+ * @param value Value to assert.
+ * @param message Optional error message when assertion fails.
+ * @returns Nothing when assertion passes; throws an `Error` on failure.
+ */
+declare function assert<T>(guard: Guard<T>, value: unknown, message?: string): asserts value is T;
+declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?: string): asserts value is B;
+
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
  *
@@ -450,6 +461,13 @@ declare const isURL: Predicate<URL>;
  * @returns Predicate narrowing to `Blob` when supported; otherwise always false.
  */
 declare const isBlob: Predicate<Blob>;
+/**
+ * Creates a guard that checks whether a value is an instance of `constructor`.
+ *
+ * @param constructor Constructor used as the right-hand side of `instanceof`.
+ * @returns Predicate narrowing to `InstanceType<C>`.
+ */
+declare const isInstanceOf: <C extends abstract new (...args: unknown[]) => unknown>(constructor: C) => Guard<InstanceType<C>>;
 
 /**
  * Checks whether a value has the specified own key.
@@ -480,4 +498,4 @@ declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <co
  */
 declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
 
-export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, and, andAll, arrayOf, define, equals, equalsBy, equalsKey, guardIn, hasKey, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFiniteNumber, isFunction, isInfiniteNumber, isInteger, isIterable, isMap, isNaN, isNegative, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, guardIn, hasKey, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };

package/dist/index.d.ts

@@ -40,6 +40,17 @@ declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
  */
 declare const predicateToRefine: <A>(fn: (value: A) => boolean) => Refine<A, A>;
 
+/**
+ * Asserts that a value satisfies a guard or refinement, otherwise throws.
+ *
+ * @param guard Guard/refinement to evaluate.
+ * @param value Value to assert.
+ * @param message Optional error message when assertion fails.
+ * @returns Nothing when assertion passes; throws an `Error` on failure.
+ */
+declare function assert<T>(guard: Guard<T>, value: unknown, message?: string): asserts value is T;
+declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?: string): asserts value is B;
+
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
  *
@@ -450,6 +461,13 @@ declare const isURL: Predicate<URL>;
  * @returns Predicate narrowing to `Blob` when supported; otherwise always false.
  */
 declare const isBlob: Predicate<Blob>;
+/**
+ * Creates a guard that checks whether a value is an instance of `constructor`.
+ *
+ * @param constructor Constructor used as the right-hand side of `instanceof`.
+ * @returns Predicate narrowing to `InstanceType<C>`.
+ */
+declare const isInstanceOf: <C extends abstract new (...args: unknown[]) => unknown>(constructor: C) => Guard<InstanceType<C>>;
 
 /**
  * Checks whether a value has the specified own key.
@@ -480,4 +498,4 @@ declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <co
  */
 declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
 
-export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, and, andAll, arrayOf, define, equals, equalsBy, equalsKey, guardIn, hasKey, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFiniteNumber, isFunction, isInfiniteNumber, isInteger, isIterable, isMap, isNaN, isNegative, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, guardIn, hasKey, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   and: () => and,
   andAll: () => andAll,
   arrayOf: () => arrayOf,
+  assert: () => assert,
   define: () => define,
   equals: () => equals,
   equalsBy: () => equalsBy,
@@ -41,6 +42,7 @@ __export(index_exports, {
   isFiniteNumber: () => isFiniteNumber,
   isFunction: () => isFunction,
   isInfiniteNumber: () => isInfiniteNumber,
+  isInstanceOf: () => isInstanceOf,
   isInteger: () => isInteger,
   isIterable: () => isIterable,
   isMap: () => isMap,
@@ -93,6 +95,13 @@ function define(fn) {
 // src/core/predicate.ts
 var predicateToRefine = (fn) => (value) => fn(value);
 
+// src/core/assert.ts
+var DEFAULT_ASSERT_MESSAGE = "Assertion failed";
+function assert(fn, value, message) {
+  if (fn(value)) return;
+  throw new Error(message ?? DEFAULT_ASSERT_MESSAGE);
+}
+
 // src/utils/to-boolean-predicates.ts
 var toBooleanPredicates = (predicates) => predicates;
 
@@ -210,6 +219,7 @@ var isError = define(
 );
 var isURL = typeof URL !== "undefined" ? define((value) => value instanceof URL) : define(() => false);
 var isBlob = typeof Blob !== "undefined" ? define((value) => value instanceof Blob) : define(() => false);
+var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
 
 // src/core/equals.ts
 function equals(target) {
@@ -394,6 +404,7 @@ function narrowKeyTo(guard, key) {
   and,
   andAll,
   arrayOf,
+  assert,
   define,
   equals,
   equalsBy,
@@ -412,6 +423,7 @@ function narrowKeyTo(guard, key) {
   isFiniteNumber,
   isFunction,
   isInfiniteNumber,
+  isInstanceOf,
   isInteger,
   isIterable,
   isMap,

package/dist/index.mjs

@@ -6,6 +6,13 @@ function define(fn) {
 // src/core/predicate.ts
 var predicateToRefine = (fn) => (value) => fn(value);
 
+// src/core/assert.ts
+var DEFAULT_ASSERT_MESSAGE = "Assertion failed";
+function assert(fn, value, message) {
+  if (fn(value)) return;
+  throw new Error(message ?? DEFAULT_ASSERT_MESSAGE);
+}
+
 // src/utils/to-boolean-predicates.ts
 var toBooleanPredicates = (predicates) => predicates;
 
@@ -123,6 +130,7 @@ var isError = define(
 );
 var isURL = typeof URL !== "undefined" ? define((value) => value instanceof URL) : define(() => false);
 var isBlob = typeof Blob !== "undefined" ? define((value) => value instanceof Blob) : define(() => false);
+var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
 
 // src/core/equals.ts
 function equals(target) {
@@ -306,6 +314,7 @@ export {
   and,
   andAll,
   arrayOf,
+  assert,
   define,
   equals,
   equalsBy,
@@ -324,6 +333,7 @@ export {
   isFiniteNumber,
   isFunction,
   isInfiniteNumber,
+  isInstanceOf,
   isInteger,
   isIterable,
   isMap,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "is-kit",
-  "version": "1.1.13",
+  "version": "1.3.0",
   "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",