is-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 @nyaomaru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# is-kit
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/nyaomaru/is-kit/main/docs/public/iskit_logo1.svg" width="200px" align="center" alt="is-kit logo" />
+</p>
+
+<p align="center">
+    <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">
+        <img src="https://img.shields.io/jsr/v/@nyaomaru/is-kit" alt="JSR">
+    </a>
+    <a href="https://github.com/nyaomaru/is-kit/blob/main/LICENSE">
+        <img src="https://img.shields.io/npm/l/@nyaomaru/is-kit.svg?sanitize=true" alt="License">
+    </a>
+</p>
+
+Lightweight, zero-dependency toolkit for building `isFoo` style type guards in TypeScript.
+Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.
+
+[👉 See full document](https://is-kit-docs.vercel.app/)
+
+## Why?
+
+Tired of writing the same `isFoo` again and again?
+Let `is-kit` do it for you:
+
+- Less boilerplate
+- Type-safe
+- Composable
+- Zero-dependency
+
+> ☕ Grab a coffee, let `is-kit` do the boring work.
+
+## Install
+
+Node via npm
+
+```bash
+pnpm add is-kit
+# or
+bun add is-kit
+# or
+npm i is-kit
+# or
+yarn add is-kit
+```
+
+ESM and CJS builds are provided for npm consumers. Types are bundled.
+
+### JSR (TypeScript source)
+
+```ts
+// Deno/Bun/JSR-aware tooling
+import { define, and, or } from 'jsr:@nyaomaru/is-kit';
+```
+
+## Quick start
+
+Build `is` functions from tiny, composable pieces:
+
+```ts
+import {
+  define,
+  predicateToRefine,
+  and,
+  or,
+  not,
+  isString,
+  isNumber,
+} from 'is-kit';
+
+// 1. define small pieces
+const isShortString = define<string>(
+  (value) => isString(value) && value.length <= 3
+);
+const isPositive = predicateToRefine<number>((num) => num > 0);
+
+// 2. compose them
+const isPositiveNumber = and(isNumber, isPositive);
+const shortOrPositive = or(isShortString, isPositiveNumber);
+const isOther = not(shortOrPositive);
+
+// 3. use them
+shortOrPositive('foo'); // true
+shortOrPositive(42); // true
+isOther(false); // true
+```
+
+These primitives plug into higher-level combinators like `struct` when you need to shape objects.
+
+## 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`.
+
+## API Reference
+
+👉 See the docs app under `docs/` (API Reference section). Each helper is documented with runnable examples.
+
+## Development
+
+Requires Node 22 and pnpm 10.12.4 (via Corepack or mise).
+Want to hack on `is-kit`?
+See `DEVELOPER.md` for setup, scripts, and contribution workflow.
+
+## Contributing
+
+See `CONTRIBUTE.md` for workflow, commit style, and tool setup. 🚀

package/dist/index.d.mts

@@ -0,0 +1,390 @@
+type Predicate<T> = (value: unknown) => value is T;
+type Refinement<A, B extends A> = (value: A) => value is B;
+type Guard<T> = Predicate<T>;
+type Refine<A, B extends A> = Refinement<A, B>;
+type RefineChain<In, T extends readonly unknown[]> = T extends [] ? [] : T extends [Refine<In, infer Next>, ...infer R] ? [Refine<In, Next>, ...RefineChain<Next, Extract<R, readonly unknown[]>>] : never;
+type ChainResult<In, T extends readonly unknown[]> = T extends [] ? In : T extends [Refine<In, infer Next>, ...infer R] ? ChainResult<Next, Extract<R, readonly unknown[]>> : never;
+type OutOfGuards<T extends readonly Guard<unknown>[]> = T[number] extends Guard<infer U> ? U : never;
+type ParseResult<T> = {
+    valid: true;
+    value: T;
+} | {
+    valid: false;
+};
+type GuardedOf<F> = F extends (value: unknown) => value is infer G ? G : never;
+type GuardedWithin<Fs, A> = Extract<Fs extends readonly unknown[] ? GuardedOf<Fs[number]> : never, A>;
+type Schema = Readonly<Record<string, Predicate<unknown>>>;
+type InferSchema<S extends Schema> = {
+    readonly [K in keyof S]: GuardedOf<S[K]>;
+};
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+/**
+ * Wraps a user function as a typed predicate.
+ *
+ * Note: The correctness of the predicate is the caller's responsibility.
+ * Its result is coerced to a boolean using `!!` for consistent guard behavior.
+ *
+ * @param fn Function that returns truthy when the value matches the target shape.
+ * @returns Predicate narrowing to the intended type when it returns true.
+ */
+declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
+declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
+
+/**
+ * Converts a boolean predicate into a refinement preserving the input type.
+ *
+ * @param fn Boolean-returning function over a value of type A.
+ * @returns Refinement equivalent to the provided predicate.
+ */
+declare const predicateToRefine: <A>(fn: (value: A) => boolean) => Refine<A, A>;
+
+/**
+ * Combines a precondition guard with an additional refinement to narrow the type.
+ *
+ * @param precondition Broad guard evaluated first; short-circuits on failure.
+ * @param condition Refinement evaluated only when `precondition` passes.
+ * @returns Predicate that narrows the input to a subtype.
+ */
+declare function and<A, B extends A>(precondition: Guard<A>, condition: Refine<A, B>): Predicate<B>;
+/**
+ * Chains a sequence of refinements after a precondition, returning the final guard type.
+ *
+ * @param precondition Initial guard applied first.
+ * @param steps Subsequent refinements applied in order.
+ * @returns Guard reflecting the result of the refinement chain.
+ */
+declare function andAll<A>(precondition: Guard<A>): Guard<A>;
+declare function andAll<A, B extends A>(precondition: Guard<A>, step1: Refine<A, B>): Guard<B>;
+declare function andAll<A, B extends A, C extends B>(precondition: Guard<A>, step1: Refine<A, B>, step2: Refine<B, C>): Guard<C>;
+/**
+ * Logical OR over multiple guards.
+ *
+ * @param guards Guards to evaluate; passes if any guard passes.
+ * @returns Guard for the union of all guarded types.
+ */
+declare function or<P extends readonly Guard<unknown>[]>(...guards: P): Guard<OutOfGuards<P>>;
+/**
+ * Adapts a guard so it can be used as a refinement within a known supertype.
+ *
+ * @returns Function that converts a `Guard<T>` into a `Refine<A, T>` when `T extends A`.
+ */
+declare function guardIn<A>(): <T extends A>(guard: Guard<T>) => Refine<A, T>;
+/**
+ * Logical negation of a guard/refinement.
+ *
+ * @param guard Guard or refinement to negate.
+ * @returns Refinement excluding the guarded subtype from the input type.
+ */
+declare function not<A, T>(guard: Guard<T>): Refine<A, Exclude<A, Extract<A, T>>>;
+declare function not<A, B extends A>(refine: Refine<A, B>): Refine<A, Exclude<A, B>>;
+
+/**
+ * Allows `null` in addition to values accepted by the given guard/refinement.
+ *
+ * @param guard Guard/refinement for the base type.
+ * @returns Guard/refinement widened to include `null`.
+ */
+declare function nullable<T>(guard: Guard<T>): Guard<T | null>;
+declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null, B | null>;
+/**
+ * Excludes `null` from the accepted values.
+ *
+ * @param guard Guard/refinement possibly including `null`.
+ * @returns Guard/refinement with `null` excluded.
+ */
+declare function nonNull<T>(guard: Guard<T>): Guard<Exclude<T, null>>;
+declare function nonNull<A, B extends A>(refine: Refine<A, B>): Refine<Exclude<A, null>, Exclude<B, null>>;
+/**
+ * Allows `null` or `undefined` in addition to values accepted by the guard.
+ *
+ * @param guard Guard/refinement for the base type.
+ * @returns Guard/refinement widened to include `null | undefined`.
+ */
+declare function nullish<T>(guard: Guard<T>): Guard<T | null | undefined>;
+declare function nullish<A, B extends A>(refine: Refine<A, B>): Refine<A | null | undefined, B | null | undefined>;
+/**
+ * Allows `undefined` in addition to values accepted by the guard.
+ *
+ * @param guard Guard/refinement for the base type.
+ * @returns Guard/refinement widened to include `undefined`.
+ */
+declare function optional<T>(guard: Guard<T>): Guard<T | undefined>;
+declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | undefined, B | undefined>;
+/**
+ * Requires a value to be present (excludes `undefined`).
+ *
+ * @param guard Guard/refinement that may accept `undefined`.
+ * @returns Guard/refinement with `undefined` removed.
+ */
+declare function required<T>(guard: Guard<T | undefined>): Guard<T>;
+declare function required<A, B extends A>(refine: Refine<A | undefined, B | undefined>): Refine<A, B>;
+
+/**
+ * Creates a guard that matches values equal to the provided target using `Object.is` semantics.
+ *
+ * @param target Target value to compare against.
+ * @returns Predicate narrowing to the exact literal type of `target`.
+ */
+declare function equals<const T>(target: T): Predicate<T>;
+/**
+ * Creates a comparator builder based on a guard and selector.
+ * Useful for checking whether a selected key or projection equals a target value.
+ *
+ * @param guard Guard for the base type before selecting a field.
+ * @param selector Optional selector to project the comparable key; if omitted, returns a function to supply it later.
+ * @returns Function that accepts a target and returns a predicate over the original value.
+ */
+declare function equalsBy<F extends (value: unknown) => value is unknown>(guard: F): <K>(selector: (value: GuardedOf<F>) => K) => <const T extends K>(target: T) => Predicate<GuardedOf<F>>;
+declare function equalsBy<F extends (value: unknown) => value is unknown, K>(guard: F, selector: (value: GuardedOf<F>) => K): <const T extends K>(target: T) => Predicate<GuardedOf<F>>;
+/**
+ * Creates a guard that matches objects having a key equal to the target value.
+ *
+ * @param key Property key to compare.
+ * @param target Value to compare using `Object.is`.
+ * @returns Predicate narrowing to objects where `key` exists and equals `target`.
+ */
+declare function equalsKey<K extends PropertyKey, const T>(key: K, target: T): <A extends Record<K, unknown>>(input: unknown) => input is A & Record<K, T>;
+
+/**
+ * Executes a guard or refinement and returns a tagged result with the value when valid.
+ *
+ * @param guard Guard/refinement to evaluate.
+ * @param value Value to check.
+ * @returns `{ valid: true, value }` when the guard passes; `{ valid: false }` otherwise.
+ */
+declare function safeParse<T>(guard: Guard<T>, value: unknown): ParseResult<T>;
+declare function safeParse<A, B extends A>(refine: Refine<A, B>, value: A): ParseResult<B>;
+declare function safeParse(fn: (value: unknown) => boolean, value: unknown): ParseResult<unknown>;
+/**
+ * Curried variant of `safeParse` for reuse.
+ *
+ * @param guard Guard/refinement to evaluate.
+ * @returns Function that takes a value and returns the `ParseResult`.
+ */
+declare function safeParseWith<T>(guard: Guard<T>): (value: unknown) => ParseResult<T>;
+declare function safeParseWith<A, B extends A>(refine: Refine<A, B>): (value: A) => ParseResult<B>;
+
+/**
+ * Checks whether a value is a string.
+ *
+ * @returns Predicate narrowing to `string`.
+ */
+declare const isString: Predicate<string>;
+/**
+ * Checks whether a value is a number primitive (may include NaN/±Infinity).
+ *
+ * @returns Predicate narrowing to `number` (primitive-only).
+ */
+declare const isNumberPrimitive: Predicate<number>;
+/**
+ * Checks whether a number is finite.
+ * @returns Refinement that accepts only finite numbers.
+ */
+declare const isFiniteNumber: Refine<number, number>;
+/**
+ * Checks whether a value is a finite number.
+ * @returns Predicate narrowing to finite `number`.
+ */
+declare const isNumber: Predicate<number>;
+/**
+ * Checks whether a value is a boolean.
+ *
+ * @returns Predicate narrowing to `boolean`.
+ */
+declare const isBoolean: Predicate<boolean>;
+/**
+ * Checks whether a value is a bigint.
+ *
+ * @returns Predicate narrowing to `bigint`.
+ */
+declare const isBigInt: Predicate<bigint>;
+/**
+ * Checks whether a value is a symbol.
+ *
+ * @returns Predicate narrowing to `symbol`.
+ */
+declare const isSymbol: Predicate<symbol>;
+/**
+ * Checks whether a value is exactly `undefined`.
+ *
+ * @returns Predicate narrowing to `undefined`.
+ */
+declare const isUndefined: Predicate<undefined>;
+/**
+ * Checks whether a value is exactly `null`.
+ *
+ * @returns Predicate narrowing to `null`.
+ */
+declare const isNull: Predicate<null>;
+
+/**
+ * Validates an array where every element satisfies the provided guard.
+ *
+ * @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>[]>;
+
+/**
+ * Validates a fixed-length tuple by applying element-wise guards.
+ *
+ * @param guards Guards corresponding to each tuple position.
+ * @returns Predicate that narrows to a readonly tuple of guarded element types.
+ */
+declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<{
+    readonly [K in keyof Fs]: GuardedOf<Fs[K]>;
+}>;
+
+/**
+ * Combines multiple guards; passes when any one guard matches.
+ *
+ * @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>;
+
+/**
+ * Validates a record-like object by guarding both keys and values.
+ *
+ * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
+ * @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>>>>;
+
+/**
+ * Validates an object against a field-to-guard schema.
+ * Keys in the schema are required; optionally rejects extra keys when `exact: true`.
+ *
+ * @param schema Record of property guards.
+ * @param options When `{ exact: true }`, disallows properties not in `schema`.
+ * @returns Predicate that narrows to the inferred struct type.
+ */
+declare function struct<S extends Schema>(schema: S, options?: {
+    exact?: boolean;
+}): Predicate<InferSchema<S>>;
+
+/**
+ * Creates a guard that matches when the input is one of the provided literal values.
+ * Uses `Object.is` for exact value semantics.
+ *
+ * @param values Literal primitives to compare against.
+ * @returns Predicate narrowing to the union of the provided literal values.
+ */
+declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...values: T): Predicate<T[number]>;
+
+/**
+ * Checks whether a value is a function.
+ *
+ * @returns Predicate narrowing to `Function`.
+ */
+declare const isFunction: Predicate<Function>;
+/**
+ * Checks for non-null objects (including arrays, dates, etc.).
+ *
+ * @returns Predicate narrowing to `Record<PropertyKey, unknown>`.
+ */
+declare const isObject: Predicate<Record<PropertyKey, unknown>>;
+/**
+ * Checks for plain objects created by object literals or `Object.create(null)`.
+ *
+ * @returns Predicate narrowing to `Record<string, unknown>`.
+ */
+declare const isPlainObject: Predicate<Record<string, unknown>>;
+/**
+ * Checks whether a value is an array.
+ *
+ * @returns Predicate narrowing to `readonly unknown[]`.
+ */
+declare const isArray: Predicate<readonly unknown[]>;
+/**
+ * Checks whether a value is a valid `Date` instance (not `Invalid Date`).
+ *
+ * @returns Predicate narrowing to `Date`.
+ */
+declare const isDate: Predicate<Date>;
+/**
+ * Checks whether a value is a `RegExp`.
+ *
+ * @returns Predicate narrowing to `RegExp`.
+ */
+declare const isRegExp: Predicate<RegExp>;
+/**
+ * Checks whether a value is a `Map`.
+ *
+ * @returns Predicate narrowing to `Map<unknown, unknown>`.
+ */
+declare const isMap: Predicate<Map<unknown, unknown>>;
+/**
+ * Checks whether a value is a `Set`.
+ *
+ * @returns Predicate narrowing to `Set<unknown>`.
+ */
+declare const isSet: Predicate<Set<unknown>>;
+/**
+ * Checks whether a value is promise-like (has a `then` function).
+ *
+ * @returns Predicate narrowing to `PromiseLike<unknown>`.
+ */
+declare const isPromiseLike: Predicate<PromiseLike<unknown>>;
+/**
+ * Checks whether a value implements the `Iterable` protocol.
+ *
+ * @returns Predicate narrowing to `Iterable<unknown>`.
+ */
+declare const isIterable: Predicate<Iterable<unknown>>;
+/**
+ * Checks whether a value implements the `AsyncIterable` protocol.
+ *
+ * @returns Predicate narrowing to `AsyncIterable<unknown>`.
+ */
+declare const isAsyncIterable: Predicate<AsyncIterable<unknown>>;
+/**
+ * Checks whether a value is an `ArrayBuffer`.
+ *
+ * @returns Predicate narrowing to `ArrayBuffer`.
+ */
+declare const isArrayBuffer: Predicate<ArrayBuffer>;
+/**
+ * Checks whether a value is a `DataView`.
+ *
+ * @returns Predicate narrowing to `DataView`.
+ */
+declare const isDataView: Predicate<DataView<ArrayBufferLike>>;
+/**
+ * Checks whether a value is a typed array view (any `ArrayBufferView` except DataView).
+ *
+ * @returns Predicate narrowing to `ArrayBufferView`.
+ */
+declare const isTypedArray: Predicate<ArrayBufferView<ArrayBufferLike>>;
+/**
+ * Checks whether a value is an `Error` (instance of Error or plain Error object tag).
+ *
+ * @returns Predicate narrowing to `Error`.
+ */
+declare const isError: Predicate<Error>;
+/**
+ * Checks whether a value is a `URL` (in environments with URL available).
+ *
+ * @returns Predicate narrowing to `URL` when supported; otherwise always false.
+ */
+declare const isURL: Predicate<URL>;
+/**
+ * Checks whether a value is a `Blob` (in environments with Blob available).
+ *
+ * @returns Predicate narrowing to `Blob` when supported; otherwise always false.
+ */
+declare const isBlob: Predicate<Blob>;
+
+/**
+ * Converts an array of guards to plain boolean predicates for iteration helpers.
+ *
+ * @param guards Guards to be treated as simple predicates.
+ * @returns Readonly array of boolean-returning functions.
+ */
+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 };