is-kit 1.0.5 → 1.1.0

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-    <a href="(https://www.npmjs.com/package/is-kit">
+    <a href="https://www.npmjs.com/package/is-kit">
         <img src="https://img.shields.io/npm/v/is-kit.svg" alt="npm version">
     </a>
     <a href="https://jsr.io/@nyaomaru/is-kit">
@@ -115,7 +115,34 @@ When validating complex shapes, reach for `struct` — and friends like `arrayOf
 - **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`.
+- **Stay ergonomic**: helpers like `nullable`, `optional`, `equals`, `safeParse`, `narrowKeyTo`.
+
+### Key Narrowing
+
+`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`.
+
+```ts
+import { narrowKeyTo, or, struct } from 'is-kit';
+
+// Base guard (e.g., via struct)
+type User = { id: string; age: number; role: 'admin' | 'guest' | 'trial' };
+const isUser = struct({
+  id: isString,
+  age: isNumber,
+  role: oneOfValues('admin', 'guest', 'trial'),
+});
+
+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 (isGuestOrTrial(value)) {
+  // value.role is 'guest' | 'trial'
+}
+```
 
 ## API Reference
 

package/dist/index.d.mts

@@ -225,7 +225,7 @@ declare const isNull: Predicate<null>;
  * @param elementGuard Guard applied to each array element.
  * @returns Predicate narrowing to a readonly array of the guarded element type.
  */
-declare function arrayOf<F extends (value: unknown) => value is unknown>(elementGuard: F): Predicate<readonly GuardedOf<F>[]>;
+declare function arrayOf<F extends Predicate<unknown>>(elementGuard: F): Predicate<readonly GuardedOf<F>[]>;
 
 /**
  * Validates a fixed-length tuple by applying element-wise guards.
@@ -243,8 +243,8 @@ declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guar
  * @param guards One or more type guards/refinements to try.
  * @returns Predicate that narrows to the union of guarded types.
  */
-declare function oneOf<Fs extends readonly ((value: unknown) => value is unknown)[]>(...guards: Fs): Predicate<GuardedOf<Fs[number]>>;
-declare function oneOf<A, Fs extends readonly ((value: A) => value is A)[]>(...guards: Fs): (input: A) => input is GuardedWithin<Fs, A>;
+declare function oneOf<Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<GuardedOf<Fs[number]>>;
+declare function oneOf<A, Fs extends readonly Predicate<A>[]>(...guards: Fs): (input: A) => input is GuardedWithin<Fs, A>;
 
 /**
  * Validates a record-like object by guarding both keys and values.
@@ -253,7 +253,7 @@ declare function oneOf<A, Fs extends readonly ((value: A) => value is A)[]>(...g
  * @param valueFunction Guard applied to each value in the record.
  * @returns Predicate narrowing to a readonly record with guarded key/value types.
  */
-declare function recordOf<KF extends (value: unknown) => value is string, VF extends (value: unknown) => value is unknown>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
+declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
 
 /**
  * Validates an object against a field-to-guard schema.
@@ -379,6 +379,20 @@ declare const isURL: Predicate<URL>;
  */
 declare const isBlob: Predicate<Blob>;
 
+/**
+ * Builds a guard that narrows a specific key to the provided literal value.
+ *
+ * Given a base guard and a property key, returns a function that accepts a
+ * target value and produces a guard of the base type intersected with
+ * `{ [key]: target }`.
+ *
+ * @param guard Base guard for objects that include `key`.
+ * @param key Property key to narrow.
+ * @returns Builder that takes a literal `target` and returns a guard that
+ * narrows `key` to that literal.
+ */
+declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => Predicate<A & Record<K, T>>;
+
 /**
  * Converts an array of guards to plain boolean predicates for iteration helpers.
  *
@@ -387,4 +401,4 @@ declare const isBlob: Predicate<Blob>;
  */
 declare const toBooleanPredicates: (guards: readonly Guard<unknown>[]) => ReadonlyArray<(value: unknown) => 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, isIterable, isMap, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPromiseLike, isRegExp, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, 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, define, equals, equalsBy, equalsKey, guardIn, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFiniteNumber, isFunction, isIterable, isMap, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPromiseLike, isRegExp, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };

package/dist/index.d.ts

@@ -225,7 +225,7 @@ declare const isNull: Predicate<null>;
  * @param elementGuard Guard applied to each array element.
  * @returns Predicate narrowing to a readonly array of the guarded element type.
  */
-declare function arrayOf<F extends (value: unknown) => value is unknown>(elementGuard: F): Predicate<readonly GuardedOf<F>[]>;
+declare function arrayOf<F extends Predicate<unknown>>(elementGuard: F): Predicate<readonly GuardedOf<F>[]>;
 
 /**
  * Validates a fixed-length tuple by applying element-wise guards.
@@ -243,8 +243,8 @@ declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guar
  * @param guards One or more type guards/refinements to try.
  * @returns Predicate that narrows to the union of guarded types.
  */
-declare function oneOf<Fs extends readonly ((value: unknown) => value is unknown)[]>(...guards: Fs): Predicate<GuardedOf<Fs[number]>>;
-declare function oneOf<A, Fs extends readonly ((value: A) => value is A)[]>(...guards: Fs): (input: A) => input is GuardedWithin<Fs, A>;
+declare function oneOf<Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<GuardedOf<Fs[number]>>;
+declare function oneOf<A, Fs extends readonly Predicate<A>[]>(...guards: Fs): (input: A) => input is GuardedWithin<Fs, A>;
 
 /**
  * Validates a record-like object by guarding both keys and values.
@@ -253,7 +253,7 @@ declare function oneOf<A, Fs extends readonly ((value: A) => value is A)[]>(...g
  * @param valueFunction Guard applied to each value in the record.
  * @returns Predicate narrowing to a readonly record with guarded key/value types.
  */
-declare function recordOf<KF extends (value: unknown) => value is string, VF extends (value: unknown) => value is unknown>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
+declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
 
 /**
  * Validates an object against a field-to-guard schema.
@@ -379,6 +379,20 @@ declare const isURL: Predicate<URL>;
  */
 declare const isBlob: Predicate<Blob>;
 
+/**
+ * Builds a guard that narrows a specific key to the provided literal value.
+ *
+ * Given a base guard and a property key, returns a function that accepts a
+ * target value and produces a guard of the base type intersected with
+ * `{ [key]: target }`.
+ *
+ * @param guard Base guard for objects that include `key`.
+ * @param key Property key to narrow.
+ * @returns Builder that takes a literal `target` and returns a guard that
+ * narrows `key` to that literal.
+ */
+declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => Predicate<A & Record<K, T>>;
+
 /**
  * Converts an array of guards to plain boolean predicates for iteration helpers.
  *
@@ -387,4 +401,4 @@ declare const isBlob: Predicate<Blob>;
  */
 declare const toBooleanPredicates: (guards: readonly Guard<unknown>[]) => ReadonlyArray<(value: unknown) => 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, isIterable, isMap, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPromiseLike, isRegExp, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, 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, define, equals, equalsBy, equalsKey, guardIn, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFiniteNumber, isFunction, isIterable, isMap, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPromiseLike, isRegExp, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };

package/dist/index.js

@@ -54,6 +54,7 @@ __export(index_exports, {
   isTypedArray: () => isTypedArray,
   isURL: () => isURL,
   isUndefined: () => isUndefined,
+  narrowKeyTo: () => narrowKeyTo,
   nonNull: () => nonNull,
   not: () => not,
   nullable: () => nullable,
@@ -275,8 +276,8 @@ function struct(schema, options) {
     if (!isPlainObject(input)) return false;
     const obj = input;
     for (const key of Object.keys(schema)) {
-      const guard = schema[key];
       if (!(key in obj)) return false;
+      const guard = schema[key];
       if (!guard(obj[key])) return false;
     }
     if (options?.exact) {
@@ -303,6 +304,16 @@ function oneOfValues(...values) {
     return valueSet.has(input);
   };
 }
+
+// src/core/key.ts
+function narrowKeyTo(guard, key) {
+  return function(target) {
+    const keyEquals = equalsKey(key, target);
+    return function(input) {
+      return guard(input) && keyEquals(input);
+    };
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   and,
@@ -339,6 +350,7 @@ function oneOfValues(...values) {
   isTypedArray,
   isURL,
   isUndefined,
+  narrowKeyTo,
   nonNull,
   not,
   nullable,

package/dist/index.mjs

@@ -200,8 +200,8 @@ function struct(schema, options) {
     if (!isPlainObject(input)) return false;
     const obj = input;
     for (const key of Object.keys(schema)) {
-      const guard = schema[key];
       if (!(key in obj)) return false;
+      const guard = schema[key];
       if (!guard(obj[key])) return false;
     }
     if (options?.exact) {
@@ -228,6 +228,16 @@ function oneOfValues(...values) {
     return valueSet.has(input);
   };
 }
+
+// src/core/key.ts
+function narrowKeyTo(guard, key) {
+  return function(target) {
+    const keyEquals = equalsKey(key, target);
+    return function(input) {
+      return guard(input) && keyEquals(input);
+    };
+  };
+}
 export {
   and,
   andAll,
@@ -263,6 +273,7 @@ export {
   isTypedArray,
   isURL,
   isUndefined,
+  narrowKeyTo,
   nonNull,
   not,
   nullable,

package/package.json

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