is-kit 1.1.12 → 1.2.0

package/README.md

@@ -162,15 +162,15 @@ isInfiniteNumber(1); // false
 - **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`, `narrowKeyTo`.
+- **Stay ergonomic**: helpers like `nullable`, `optional`, `equals`, `safeParse`, `assert`, `hasKey`, `narrowKeyTo`.
 
-### Key Narrowing
+### Key Helpers
 
-`equalsBy` preserves the base type and does not narrow selected fields to literals.
-When you need to narrow a property to a specific literal value, use `narrowKeyTo`.
+Use `hasKey` to check for a required own property before refining, and
+`narrowKeyTo` when you need to narrow a property to a specific literal value.
 
 ```ts
-import { narrowKeyTo, or, struct } from 'is-kit';
+import { hasKey, isString, isNumber, narrowKeyTo, or, struct } from 'is-kit';
 
 // Base guard (e.g., via struct)
 type User = { id: string; age: number; role: 'admin' | 'guest' | 'trial' };
@@ -180,12 +180,17 @@ const isUser = struct({
   role: oneOfValues('admin', 'guest', 'trial')
 });
 
+const hasRole = hasKey('role');
 const byRole = narrowKeyTo(isUser, 'role');
 const isGuest = byRole('guest'); // Readonly<User> & { role: 'guest' }
 const isTrial = byRole('trial'); // Readonly<User> & { role: 'trial' }
 const isGuestOrTrial = or(isGuest, isTrial);
 
 declare const value: unknown;
+if (hasRole(value)) {
+  value.role;
+}
+
 if (isGuestOrTrial(value)) {
   // value.role is 'guest' | 'trial'
 }

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.
  *
@@ -451,6 +462,13 @@ declare const isURL: Predicate<URL>;
  */
 declare const isBlob: Predicate<Blob>;
 
+/**
+ * Checks whether a value has the specified own key.
+ *
+ * @param key Property key to check.
+ * @returns Predicate narrowing to an object with the key present.
+ */
+declare const hasKey: <K extends PropertyKey>(key: K) => Predicate<Record<K, unknown>>;
 /**
  * Builds a guard that narrows a specific key to the provided literal value.
  *
@@ -473,4 +491,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, 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, 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.
  *
@@ -451,6 +462,13 @@ declare const isURL: Predicate<URL>;
  */
 declare const isBlob: Predicate<Blob>;
 
+/**
+ * Checks whether a value has the specified own key.
+ *
+ * @param key Property key to check.
+ * @returns Predicate narrowing to an object with the key present.
+ */
+declare const hasKey: <K extends PropertyKey>(key: K) => Predicate<Record<K, unknown>>;
 /**
  * Builds a guard that narrows a specific key to the provided literal value.
  *
@@ -473,4 +491,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, 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, 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,11 +23,13 @@ __export(index_exports, {
   and: () => and,
   andAll: () => andAll,
   arrayOf: () => arrayOf,
+  assert: () => assert,
   define: () => define,
   equals: () => equals,
   equalsBy: () => equalsBy,
   equalsKey: () => equalsKey,
   guardIn: () => guardIn,
+  hasKey: () => hasKey,
   isArray: () => isArray,
   isArrayBuffer: () => isArrayBuffer,
   isAsyncIterable: () => isAsyncIterable,
@@ -92,6 +94,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;
 
@@ -377,6 +386,9 @@ function oneOfValues(...args) {
 }
 
 // src/core/key.ts
+var hasKey = (key) => define(
+  (input) => isObject(input) && Object.prototype.hasOwnProperty.call(input, key)
+);
 function narrowKeyTo(guard, key) {
   return function(target) {
     const keyEquals = equalsKey(key, target);
@@ -390,11 +402,13 @@ function narrowKeyTo(guard, key) {
   and,
   andAll,
   arrayOf,
+  assert,
   define,
   equals,
   equalsBy,
   equalsKey,
   guardIn,
+  hasKey,
   isArray,
   isArrayBuffer,
   isAsyncIterable,

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;
 
@@ -291,6 +298,9 @@ function oneOfValues(...args) {
 }
 
 // src/core/key.ts
+var hasKey = (key) => define(
+  (input) => isObject(input) && Object.prototype.hasOwnProperty.call(input, key)
+);
 function narrowKeyTo(guard, key) {
   return function(target) {
     const keyEquals = equalsKey(key, target);
@@ -303,11 +313,13 @@ export {
   and,
   andAll,
   arrayOf,
+  assert,
   define,
   equals,
   equalsBy,
   equalsKey,
   guardIn,
+  hasKey,
   isArray,
   isArrayBuffer,
   isAsyncIterable,

package/package.json

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