is-kit 1.10.0 → 1.11.1

package/README.md

@@ -111,6 +111,69 @@ This is the core idea of `is-kit`:
 2. Compose them.
 3. Reuse them anywhere TypeScript narrowing matters.
 
+## 🧭 Guard Composition Guide
+
+When writing reusable guards with `is-kit`, start from the library primitives:
+use `define` for custom runtime checks, and use logic combinators such as
+`and`, `or`, and `not` when combining existing guards. This keeps the result
+reusable as a named guard and preserves the type-level intent in hover,
+completion, and generated declarations.
+
+```ts
+import {
+  and,
+  define,
+  isNil,
+  isNumber,
+  isString,
+  nullish,
+  or,
+  predicateToRefine
+} from 'is-kit';
+
+const isId = or(isString, isNumber);
+const isNullishString = nullish(isString);
+
+const isSlug = define<string>(
+  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+);
+
+const isPositiveNumber = and(
+  isNumber,
+  predicateToRefine<number>((value) => value > 0)
+);
+
+isNil(null); // true
+isNil(undefined); // true
+isId('user-1'); // true
+isNullishString(undefined); // true
+isSlug('release-110'); // true
+isPositiveNumber(1); // true
+```
+
+Prefer these forms when generating or reviewing code:
+
+```ts
+declare const value: unknown;
+
+// Prefer
+const isId = or(isString, isNumber);
+const isMaybeName = nullish(isString);
+const isSlug = define<string>(
+  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+);
+
+// Avoid
+const isId = (value: unknown) => isString(value) || isNumber(value);
+const isMaybeName = (value: unknown) => value == null || isString(value);
+const isSlug = (value: unknown): value is string =>
+  isString(value) && /^[a-z0-9-]+$/.test(value);
+```
+
+For AI agents or repository-wide conventions, copy
+[docs/agent-rules.md](./docs/agent-rules.md) into the consumer repository's
+agent instructions.
+
 ## ⌚ A 30-second Mental Model
 
 If you are new to the library, these are the pieces to remember:
@@ -270,6 +333,17 @@ const isDefinedString = required(optional(isString));
 const isNonNullString = nonNull(nullable(isString));
 ```
 
+For a plain "is it `null` or `undefined`?" check, reach for `isNil` instead of
+hand-rolling `isNull(x) || isUndefined(x)`:
+
+```ts
+import { isNil } from 'is-kit';
+
+isNil(null); // true
+isNil(undefined); // true
+isNil(0); // false
+```
+
 ### 8. Parse or assert unknown input
 
 Use `safeParse` when you want a result object, and `assert` when invalid data should stop execution.
@@ -434,7 +508,7 @@ The library is organized around a few small building blocks:
 - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`
 - **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
 - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
-- **Nullish handling**: `nullable`, `nonNull`, `nullish`, `optional`, `required`
+- **Nullish handling**: `isNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
 - **Result helpers**: `safeParse`, `safeParseWith`, `safeJsonParse`, `assert`
 
 For the full API list and dedicated pages, use the docs site below.

package/dist/index.d.mts

@@ -1,3 +1,11 @@
+/**
+ * is-kit guard authoring guide:
+ * - Use define<T>(...) for reusable custom runtime checks.
+ * - Use and, andAll, or, and not to compose existing guards instead of
+ *   hand-written boolean wrappers.
+ * - Use nullable, optional, or nullish to widen guards for nullish values.
+ * - Use struct or typedStruct for object-shape guards.
+ */
 type Predicate<T> = (value: unknown) => value is T;
 type Refinement<A, B extends A> = (value: A) => value is B;
 type Guard<T> = Predicate<T>;
@@ -69,12 +77,18 @@ declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?
 
 /**
  * Wraps a user function as a typed predicate.
+ * Prefer `define<T>(...)` when creating a reusable custom guard from a runtime
+ * boolean check.
  *
  * 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.
+ * @example
+ * const isSlug = define<string>(
+ *   (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+ * );
  */
 declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
 declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
@@ -146,49 +160,76 @@ declare function lazy<T>(factory: () => Predicate<T>): Predicate<T>;
 
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
+ * Prefer this over hand-written `precondition(x) && condition(x)` when the
+ * composed predicate should be reused as a guard.
  *
  * @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.
+ * @example
+ * const isPositiveNumber = and(
+ *   isNumber,
+ *   predicateToRefine<number>((value) => value > 0)
+ * );
+ * @see andAll
  */
 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.
+ * Use this instead of nested `&&` checks when each step should keep narrowing
+ * the next refinement.
  *
  * @param precondition Initial guard applied first.
  * @param steps Subsequent refinements applied in order.
  * @returns Guard reflecting the result of the refinement chain.
+ * @example
+ * const isPublicTitle = andAll(isString, minLength(4), startsWithPublic);
+ * @see and
  */
 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.
+ * Prefer this over hand-written `guardA(x) || guardB(x)` when the composed
+ * predicate should be reused as a guard.
  *
  * @param guards Guards to evaluate; passes if any guard passes.
  * @returns Guard for the union of all guarded types.
+ * @example
+ * const isId = or(isString, isNumber);
+ * @see oneOf
  */
 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`.
+ * @see and
  */
 declare function guardIn<A>(): <T extends A>(guard: Guard<T>) => Refine<A, T>;
 /**
  * Logical negation of a guard/refinement.
+ * Use this when a negated predicate should be named and reused.
  *
  * @param guard Guard or refinement to negate.
  * @returns Refinement excluding the guarded subtype from the input type.
+ * @example
+ * const isPresent = not(isNil);
  */
 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.
+ * Use this instead of hand-writing `value === null || guard(value)` when the
+ * widened predicate should stay reusable.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null`.
+ * @example
+ * const isNullableString = nullable(isString);
+ * @see nullish
  */
 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>;
@@ -197,22 +238,33 @@ declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null
  *
  * @param guard Guard/refinement possibly including `null`.
  * @returns Guard/refinement with `null` excluded.
+ * @example
+ * const isNonNullString = nonNull(nullable(isString));
  */
 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.
+ * Use this instead of hand-writing `isNil(value) || guard(value)` when widening
+ * another guard.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null | undefined`.
+ * @example
+ * const isNullishString = nullish(isString);
+ * @see isNil
  */
 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.
+ * Use this for value-level optionality. For optional object keys in `struct`,
+ * use `optionalKey(...)`.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `undefined`.
+ * @example
+ * const isOptionalString = optional(isString);
  */
 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>;
@@ -221,6 +273,8 @@ declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | unde
  *
  * @param guard Guard/refinement that may accept `undefined`.
  * @returns Guard/refinement with `undefined` removed.
+ * @example
+ * const isRequiredString = required(optional(isString));
  */
 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>;
@@ -351,15 +405,38 @@ declare const isSymbol: Predicate<symbol>;
 /**
  * Checks whether a value is exactly `undefined`.
  *
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
+ *
  * @returns Predicate narrowing to `undefined`.
+ * @see isNil
  */
 declare const isUndefined: Predicate<undefined>;
 /**
  * Checks whether a value is exactly `null`.
  *
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
+ *
  * @returns Predicate narrowing to `null`.
+ * @see isNil
  */
 declare const isNull: Predicate<null>;
+/**
+ * Checks whether a value is `null` or `undefined` (nullish).
+ *
+ * Prefer this over hand-rolling `isNull(x) || isUndefined(x)`: it is the same
+ * check expressed once. To widen an existing guard so it also accepts nullish
+ * values, use {@link nullish} instead.
+ *
+ * @returns Predicate narrowing to `null | undefined`.
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * @see or
+ */
+declare const isNil: Guard<null | undefined>;
 /**
  * Checks whether a value is a JavaScript primitive.
  *
@@ -485,6 +562,12 @@ declare const isURL: Guard<URL>;
  * @returns Predicate narrowing to `Blob` when supported; otherwise always false.
  */
 declare const isBlob: Guard<Blob>;
+/**
+ * Checks whether a value is a `File` (in environments with File available).
+ *
+ * @returns Predicate narrowing to `File` when supported; otherwise always false.
+ */
+declare const isFile: Guard<File>;
 /**
  * Creates a guard that checks whether a value is an instance of `constructor`.
  *
@@ -613,6 +696,7 @@ declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guar
     readonly [K in keyof Fs]: GuardedOf<Fs[K]>;
 }>;
 
+type BooleanPredicate<T> = (value: T) => boolean;
 /**
  * Checks whether every array element satisfies the provided predicate.
  *
@@ -620,7 +704,7 @@ declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guar
  * @param predicate Predicate applied to each element.
  * @returns Whether all elements satisfy `predicate`.
  */
-declare const everyArrayValue: (values: readonly unknown[], predicate: (value: unknown) => boolean) => boolean;
+declare const everyArrayValue: (values: readonly unknown[], predicate: BooleanPredicate<unknown>) => boolean;
 /**
  * Checks whether a tuple matches the provided element predicates in order.
  *
@@ -628,7 +712,7 @@ declare const everyArrayValue: (values: readonly unknown[], predicate: (value: u
  * @param predicates Predicates aligned to each tuple index.
  * @returns Whether lengths match and each index passes.
  */
-declare const everyTupleValue: (values: readonly unknown[], predicates: readonly ((value: unknown) => boolean)[]) => boolean;
+declare const everyTupleValue: (values: readonly unknown[], predicates: readonly BooleanPredicate<unknown>[]) => boolean;
 /**
  * Checks whether every set value satisfies the provided predicate.
  *
@@ -636,7 +720,7 @@ declare const everyTupleValue: (values: readonly unknown[], predicates: readonly
  * @param predicate Predicate applied to each value.
  * @returns Whether all set values satisfy `predicate`.
  */
-declare const everySetValue: (values: ReadonlySet<unknown>, predicate: (value: unknown) => boolean) => boolean;
+declare const everySetValue: (values: ReadonlySet<unknown>, predicate: BooleanPredicate<unknown>) => boolean;
 /**
  * Checks whether every map entry satisfies the provided key and value predicates.
  *
@@ -645,7 +729,7 @@ declare const everySetValue: (values: ReadonlySet<unknown>, predicate: (value: u
  * @param valuePredicate Predicate applied to each value.
  * @returns Whether all keys and values satisfy their predicates.
  */
-declare const everyMapEntry: (values: ReadonlyMap<unknown, unknown>, keyPredicate: (key: unknown) => boolean, valuePredicate: (value: unknown) => boolean) => boolean;
+declare const everyMapEntry: (values: ReadonlyMap<unknown, unknown>, keyPredicate: BooleanPredicate<unknown>, valuePredicate: BooleanPredicate<unknown>) => boolean;
 /**
  * Checks whether every own enumerable string key/value pair satisfies the provided predicates.
  *
@@ -654,7 +738,7 @@ declare const everyMapEntry: (values: ReadonlyMap<unknown, unknown>, keyPredicat
  * @param valuePredicate Predicate applied to each corresponding value.
  * @returns Whether all enumerable entries satisfy their predicates.
  */
-declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPredicate: (key: string) => boolean, valuePredicate: (value: unknown) => boolean) => boolean;
+declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPredicate: BooleanPredicate<string>, valuePredicate: BooleanPredicate<unknown>) => boolean;
 
 /**
  * Converts predicates to plain boolean predicates for iteration helpers.
@@ -664,4 +748,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
  */
 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 OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, type SchemaField, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, 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, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, type SchemaField, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * is-kit guard authoring guide:
+ * - Use define<T>(...) for reusable custom runtime checks.
+ * - Use and, andAll, or, and not to compose existing guards instead of
+ *   hand-written boolean wrappers.
+ * - Use nullable, optional, or nullish to widen guards for nullish values.
+ * - Use struct or typedStruct for object-shape guards.
+ */
 type Predicate<T> = (value: unknown) => value is T;
 type Refinement<A, B extends A> = (value: A) => value is B;
 type Guard<T> = Predicate<T>;
@@ -69,12 +77,18 @@ declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?
 
 /**
  * Wraps a user function as a typed predicate.
+ * Prefer `define<T>(...)` when creating a reusable custom guard from a runtime
+ * boolean check.
  *
  * 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.
+ * @example
+ * const isSlug = define<string>(
+ *   (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+ * );
  */
 declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
 declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
@@ -146,49 +160,76 @@ declare function lazy<T>(factory: () => Predicate<T>): Predicate<T>;
 
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
+ * Prefer this over hand-written `precondition(x) && condition(x)` when the
+ * composed predicate should be reused as a guard.
  *
  * @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.
+ * @example
+ * const isPositiveNumber = and(
+ *   isNumber,
+ *   predicateToRefine<number>((value) => value > 0)
+ * );
+ * @see andAll
  */
 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.
+ * Use this instead of nested `&&` checks when each step should keep narrowing
+ * the next refinement.
  *
  * @param precondition Initial guard applied first.
  * @param steps Subsequent refinements applied in order.
  * @returns Guard reflecting the result of the refinement chain.
+ * @example
+ * const isPublicTitle = andAll(isString, minLength(4), startsWithPublic);
+ * @see and
  */
 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.
+ * Prefer this over hand-written `guardA(x) || guardB(x)` when the composed
+ * predicate should be reused as a guard.
  *
  * @param guards Guards to evaluate; passes if any guard passes.
  * @returns Guard for the union of all guarded types.
+ * @example
+ * const isId = or(isString, isNumber);
+ * @see oneOf
  */
 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`.
+ * @see and
  */
 declare function guardIn<A>(): <T extends A>(guard: Guard<T>) => Refine<A, T>;
 /**
  * Logical negation of a guard/refinement.
+ * Use this when a negated predicate should be named and reused.
  *
  * @param guard Guard or refinement to negate.
  * @returns Refinement excluding the guarded subtype from the input type.
+ * @example
+ * const isPresent = not(isNil);
  */
 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.
+ * Use this instead of hand-writing `value === null || guard(value)` when the
+ * widened predicate should stay reusable.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null`.
+ * @example
+ * const isNullableString = nullable(isString);
+ * @see nullish
  */
 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>;
@@ -197,22 +238,33 @@ declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null
  *
  * @param guard Guard/refinement possibly including `null`.
  * @returns Guard/refinement with `null` excluded.
+ * @example
+ * const isNonNullString = nonNull(nullable(isString));
  */
 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.
+ * Use this instead of hand-writing `isNil(value) || guard(value)` when widening
+ * another guard.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null | undefined`.
+ * @example
+ * const isNullishString = nullish(isString);
+ * @see isNil
  */
 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.
+ * Use this for value-level optionality. For optional object keys in `struct`,
+ * use `optionalKey(...)`.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `undefined`.
+ * @example
+ * const isOptionalString = optional(isString);
  */
 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>;
@@ -221,6 +273,8 @@ declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | unde
  *
  * @param guard Guard/refinement that may accept `undefined`.
  * @returns Guard/refinement with `undefined` removed.
+ * @example
+ * const isRequiredString = required(optional(isString));
  */
 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>;
@@ -351,15 +405,38 @@ declare const isSymbol: Predicate<symbol>;
 /**
  * Checks whether a value is exactly `undefined`.
  *
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
+ *
  * @returns Predicate narrowing to `undefined`.
+ * @see isNil
  */
 declare const isUndefined: Predicate<undefined>;
 /**
  * Checks whether a value is exactly `null`.
  *
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
+ *
  * @returns Predicate narrowing to `null`.
+ * @see isNil
  */
 declare const isNull: Predicate<null>;
+/**
+ * Checks whether a value is `null` or `undefined` (nullish).
+ *
+ * Prefer this over hand-rolling `isNull(x) || isUndefined(x)`: it is the same
+ * check expressed once. To widen an existing guard so it also accepts nullish
+ * values, use {@link nullish} instead.
+ *
+ * @returns Predicate narrowing to `null | undefined`.
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * @see or
+ */
+declare const isNil: Guard<null | undefined>;
 /**
  * Checks whether a value is a JavaScript primitive.
  *
@@ -485,6 +562,12 @@ declare const isURL: Guard<URL>;
  * @returns Predicate narrowing to `Blob` when supported; otherwise always false.
  */
 declare const isBlob: Guard<Blob>;
+/**
+ * Checks whether a value is a `File` (in environments with File available).
+ *
+ * @returns Predicate narrowing to `File` when supported; otherwise always false.
+ */
+declare const isFile: Guard<File>;
 /**
  * Creates a guard that checks whether a value is an instance of `constructor`.
  *
@@ -613,6 +696,7 @@ declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guar
     readonly [K in keyof Fs]: GuardedOf<Fs[K]>;
 }>;
 
+type BooleanPredicate<T> = (value: T) => boolean;
 /**
  * Checks whether every array element satisfies the provided predicate.
  *
@@ -620,7 +704,7 @@ declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guar
  * @param predicate Predicate applied to each element.
  * @returns Whether all elements satisfy `predicate`.
  */
-declare const everyArrayValue: (values: readonly unknown[], predicate: (value: unknown) => boolean) => boolean;
+declare const everyArrayValue: (values: readonly unknown[], predicate: BooleanPredicate<unknown>) => boolean;
 /**
  * Checks whether a tuple matches the provided element predicates in order.
  *
@@ -628,7 +712,7 @@ declare const everyArrayValue: (values: readonly unknown[], predicate: (value: u
  * @param predicates Predicates aligned to each tuple index.
  * @returns Whether lengths match and each index passes.
  */
-declare const everyTupleValue: (values: readonly unknown[], predicates: readonly ((value: unknown) => boolean)[]) => boolean;
+declare const everyTupleValue: (values: readonly unknown[], predicates: readonly BooleanPredicate<unknown>[]) => boolean;
 /**
  * Checks whether every set value satisfies the provided predicate.
  *
@@ -636,7 +720,7 @@ declare const everyTupleValue: (values: readonly unknown[], predicates: readonly
  * @param predicate Predicate applied to each value.
  * @returns Whether all set values satisfy `predicate`.
  */
-declare const everySetValue: (values: ReadonlySet<unknown>, predicate: (value: unknown) => boolean) => boolean;
+declare const everySetValue: (values: ReadonlySet<unknown>, predicate: BooleanPredicate<unknown>) => boolean;
 /**
  * Checks whether every map entry satisfies the provided key and value predicates.
  *
@@ -645,7 +729,7 @@ declare const everySetValue: (values: ReadonlySet<unknown>, predicate: (value: u
  * @param valuePredicate Predicate applied to each value.
  * @returns Whether all keys and values satisfy their predicates.
  */
-declare const everyMapEntry: (values: ReadonlyMap<unknown, unknown>, keyPredicate: (key: unknown) => boolean, valuePredicate: (value: unknown) => boolean) => boolean;
+declare const everyMapEntry: (values: ReadonlyMap<unknown, unknown>, keyPredicate: BooleanPredicate<unknown>, valuePredicate: BooleanPredicate<unknown>) => boolean;
 /**
  * Checks whether every own enumerable string key/value pair satisfies the provided predicates.
  *
@@ -654,7 +738,7 @@ declare const everyMapEntry: (values: ReadonlyMap<unknown, unknown>, keyPredicat
  * @param valuePredicate Predicate applied to each corresponding value.
  * @returns Whether all enumerable entries satisfy their predicates.
  */
-declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPredicate: (key: string) => boolean, valuePredicate: (value: unknown) => boolean) => boolean;
+declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPredicate: BooleanPredicate<string>, valuePredicate: BooleanPredicate<unknown>) => boolean;
 
 /**
  * Converts predicates to plain boolean predicates for iteration helpers.
@@ -664,4 +748,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
  */
 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 OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, type SchemaField, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, 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, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, type SchemaField, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };

package/dist/index.js

@@ -45,6 +45,7 @@ __export(index_exports, {
   isDataView: () => isDataView,
   isDate: () => isDate,
   isError: () => isError,
+  isFile: () => isFile,
   isFiniteNumber: () => isFiniteNumber,
   isFunction: () => isFunction,
   isInfiniteNumber: () => isInfiniteNumber,
@@ -54,6 +55,7 @@ __export(index_exports, {
   isMap: () => isMap,
   isNaN: () => isNaN,
   isNegative: () => isNegative,
+  isNil: () => isNil,
   isNull: () => isNull,
   isNumber: () => isNumber,
   isNumberPrimitive: () => isNumberPrimitive,
@@ -112,6 +114,42 @@ function define(fn) {
   return (value) => !!fn(value);
 }
 
+// src/utils/own-properties.ts
+var hasOwnPropertyKey = (value, key) => Object.hasOwn(value, key);
+var hasOwnPropertyKeys = (value, keys) => keys.every((key) => hasOwnPropertyKey(value, key));
+
+// src/utils/guard-collections.ts
+var everyIterableValue = (values, predicate) => {
+  for (const value of values) {
+    if (!predicate(value)) return false;
+  }
+  return true;
+};
+var everyKeyValueEntry = (entries, predicate) => {
+  for (const [key, value] of entries) {
+    if (!predicate(key, value)) return false;
+  }
+  return true;
+};
+var everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
+var everyTupleValue = (values, predicates) => {
+  if (values.length !== predicates.length) return false;
+  for (let index = 0; index < predicates.length; index += 1) {
+    const predicate = predicates[index];
+    if (!predicate(values[index])) return false;
+  }
+  return true;
+};
+var everySetValue = (values, predicate) => everyIterableValue(values, predicate);
+var everyMapEntry = (values, keyPredicate, valuePredicate) => everyKeyValueEntry(
+  values,
+  (key, value) => keyPredicate(key) && valuePredicate(value)
+);
+var everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyIterableValue(
+  Object.keys(values),
+  (key) => keyPredicate(key) && valuePredicate(values[key])
+);
+
 // src/utils/object-tags.ts
 var objectToString = Object.prototype.toString;
 var OBJECT_TAG_DATE = "[object Date]";
@@ -125,6 +163,9 @@ var OBJECT_TAG_DATA_VIEW = "[object DataView]";
 var OBJECT_TAG_ERROR = "[object Error]";
 var getTag = (value) => objectToString.call(value);
 
+// src/utils/to-boolean-predicates.ts
+var toBooleanPredicates = (predicates) => predicates;
+
 // src/core/object.ts
 var defineTagGuard = (tag) => define((value) => getTag(value) === tag);
 var defineOptionalInstanceGuard = (constructor) => constructor === void 0 ? define(() => false) : define(
@@ -177,6 +218,9 @@ var isURL = defineOptionalInstanceGuard(
 var isBlob = defineOptionalInstanceGuard(
   typeof Blob === "undefined" ? void 0 : Blob
 );
+var isFile = defineOptionalInstanceGuard(
+  typeof File === "undefined" ? void 0 : File
+);
 var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
 
 // src/core/equals.ts
@@ -197,19 +241,19 @@ function equalsBy(guard, selector) {
 }
 function equalsKey(key, target) {
   const hasMatchingKey = define((input) => {
-    return isObject(input) && Object.hasOwn(input, key) && Object.is(input[key], target);
+    return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
   });
   return (input) => hasMatchingKey(input);
 }
 
 // src/core/key.ts
-var hasKey = (key) => define((input) => isObject(input) && Object.hasOwn(input, key));
+var hasKey = (key) => define((input) => isObject(input) && hasOwnPropertyKey(input, key));
 var hasKeys = (...keys) => {
   if (keys.length === 0) {
     return define(() => false);
   }
   return define(
-    (input) => isObject(input) && keys.every((key) => Object.hasOwn(input, key))
+    (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
   );
 };
 function narrowKeyTo(guard, key) {
@@ -230,42 +274,6 @@ function lazy(factory) {
   };
 }
 
-// src/utils/guard-collections.ts
-var everyArrayValue = (values, predicate) => {
-  for (const value of values) {
-    if (!predicate(value)) return false;
-  }
-  return true;
-};
-var everyTupleValue = (values, predicates) => {
-  if (values.length !== predicates.length) return false;
-  for (const [index, predicate] of predicates.entries()) {
-    if (!predicate(values[index])) return false;
-  }
-  return true;
-};
-var everySetValue = (values, predicate) => {
-  for (const value of values) {
-    if (!predicate(value)) return false;
-  }
-  return true;
-};
-var everyMapEntry = (values, keyPredicate, valuePredicate) => {
-  for (const [key, value] of values) {
-    if (!keyPredicate(key) || !valuePredicate(value)) return false;
-  }
-  return true;
-};
-var everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => {
-  for (const key of Object.keys(values)) {
-    if (!keyPredicate(key) || !valuePredicate(values[key])) return false;
-  }
-  return true;
-};
-
-// src/utils/to-boolean-predicates.ts
-var toBooleanPredicates = (predicates) => predicates;
-
 // src/core/logic.ts
 function and(precondition, condition) {
   return define((input) => {
@@ -372,6 +380,7 @@ var isBigInt = define((value) => typeof value === "bigint");
 var isSymbol = define((value) => typeof value === "symbol");
 var isUndefined = define((value) => value === void 0);
 var isNull = define((value) => value === null);
+var isNil = or(isNull, isUndefined);
 var isPrimitive = or(
   isString,
   isNumberPrimitive,
@@ -464,12 +473,14 @@ var isOptionalSchemaField = define(
 var hasRequiredKeys = (obj, entries) => (
   // WHY: Required fields must be own properties; inherited values should not
   // satisfy a schema because `struct` models object payload shape, not prototype chains.
-  entries.every(([key, guard]) => Object.hasOwn(obj, key) && guard(obj[key]))
+  entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]))
 );
 var hasValidOptionalKeys = (obj, entries) => (
   // WHY: Optional keys are validated only when present. Missing keys stay valid
   // without forcing callers to encode `undefined` into the value guard.
-  entries.every(([key, guard]) => !Object.hasOwn(obj, key) || guard(obj[key]))
+  entries.every(
+    ([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key])
+  )
 );
 var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
 function optionalKey(guard) {
@@ -480,7 +491,7 @@ function struct(schema, options) {
   const optionalEntries = [];
   const schemaKeys = [];
   for (const key in schema) {
-    if (!Object.hasOwn(schema, key)) continue;
+    if (!hasOwnPropertyKey(schema, key)) continue;
     const field = schema[key];
     schemaKeys.push(key);
     if (isOptionalSchemaField(field)) {
@@ -542,6 +553,7 @@ function tupleOf(...guards) {
   isDataView,
   isDate,
   isError,
+  isFile,
   isFiniteNumber,
   isFunction,
   isInfiniteNumber,
@@ -551,6 +563,7 @@ function tupleOf(...guards) {
   isMap,
   isNaN,
   isNegative,
+  isNil,
   isNull,
   isNumber,
   isNumberPrimitive,

package/dist/index.mjs

@@ -10,6 +10,42 @@ function define(fn) {
   return (value) => !!fn(value);
 }
 
+// src/utils/own-properties.ts
+var hasOwnPropertyKey = (value, key) => Object.hasOwn(value, key);
+var hasOwnPropertyKeys = (value, keys) => keys.every((key) => hasOwnPropertyKey(value, key));
+
+// src/utils/guard-collections.ts
+var everyIterableValue = (values, predicate) => {
+  for (const value of values) {
+    if (!predicate(value)) return false;
+  }
+  return true;
+};
+var everyKeyValueEntry = (entries, predicate) => {
+  for (const [key, value] of entries) {
+    if (!predicate(key, value)) return false;
+  }
+  return true;
+};
+var everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
+var everyTupleValue = (values, predicates) => {
+  if (values.length !== predicates.length) return false;
+  for (let index = 0; index < predicates.length; index += 1) {
+    const predicate = predicates[index];
+    if (!predicate(values[index])) return false;
+  }
+  return true;
+};
+var everySetValue = (values, predicate) => everyIterableValue(values, predicate);
+var everyMapEntry = (values, keyPredicate, valuePredicate) => everyKeyValueEntry(
+  values,
+  (key, value) => keyPredicate(key) && valuePredicate(value)
+);
+var everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyIterableValue(
+  Object.keys(values),
+  (key) => keyPredicate(key) && valuePredicate(values[key])
+);
+
 // src/utils/object-tags.ts
 var objectToString = Object.prototype.toString;
 var OBJECT_TAG_DATE = "[object Date]";
@@ -23,6 +59,9 @@ var OBJECT_TAG_DATA_VIEW = "[object DataView]";
 var OBJECT_TAG_ERROR = "[object Error]";
 var getTag = (value) => objectToString.call(value);
 
+// src/utils/to-boolean-predicates.ts
+var toBooleanPredicates = (predicates) => predicates;
+
 // src/core/object.ts
 var defineTagGuard = (tag) => define((value) => getTag(value) === tag);
 var defineOptionalInstanceGuard = (constructor) => constructor === void 0 ? define(() => false) : define(
@@ -75,6 +114,9 @@ var isURL = defineOptionalInstanceGuard(
 var isBlob = defineOptionalInstanceGuard(
   typeof Blob === "undefined" ? void 0 : Blob
 );
+var isFile = defineOptionalInstanceGuard(
+  typeof File === "undefined" ? void 0 : File
+);
 var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
 
 // src/core/equals.ts
@@ -95,19 +137,19 @@ function equalsBy(guard, selector) {
 }
 function equalsKey(key, target) {
   const hasMatchingKey = define((input) => {
-    return isObject(input) && Object.hasOwn(input, key) && Object.is(input[key], target);
+    return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
   });
   return (input) => hasMatchingKey(input);
 }
 
 // src/core/key.ts
-var hasKey = (key) => define((input) => isObject(input) && Object.hasOwn(input, key));
+var hasKey = (key) => define((input) => isObject(input) && hasOwnPropertyKey(input, key));
 var hasKeys = (...keys) => {
   if (keys.length === 0) {
     return define(() => false);
   }
   return define(
-    (input) => isObject(input) && keys.every((key) => Object.hasOwn(input, key))
+    (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
   );
 };
 function narrowKeyTo(guard, key) {
@@ -128,42 +170,6 @@ function lazy(factory) {
   };
 }
 
-// src/utils/guard-collections.ts
-var everyArrayValue = (values, predicate) => {
-  for (const value of values) {
-    if (!predicate(value)) return false;
-  }
-  return true;
-};
-var everyTupleValue = (values, predicates) => {
-  if (values.length !== predicates.length) return false;
-  for (const [index, predicate] of predicates.entries()) {
-    if (!predicate(values[index])) return false;
-  }
-  return true;
-};
-var everySetValue = (values, predicate) => {
-  for (const value of values) {
-    if (!predicate(value)) return false;
-  }
-  return true;
-};
-var everyMapEntry = (values, keyPredicate, valuePredicate) => {
-  for (const [key, value] of values) {
-    if (!keyPredicate(key) || !valuePredicate(value)) return false;
-  }
-  return true;
-};
-var everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => {
-  for (const key of Object.keys(values)) {
-    if (!keyPredicate(key) || !valuePredicate(values[key])) return false;
-  }
-  return true;
-};
-
-// src/utils/to-boolean-predicates.ts
-var toBooleanPredicates = (predicates) => predicates;
-
 // src/core/logic.ts
 function and(precondition, condition) {
   return define((input) => {
@@ -270,6 +276,7 @@ var isBigInt = define((value) => typeof value === "bigint");
 var isSymbol = define((value) => typeof value === "symbol");
 var isUndefined = define((value) => value === void 0);
 var isNull = define((value) => value === null);
+var isNil = or(isNull, isUndefined);
 var isPrimitive = or(
   isString,
   isNumberPrimitive,
@@ -362,12 +369,14 @@ var isOptionalSchemaField = define(
 var hasRequiredKeys = (obj, entries) => (
   // WHY: Required fields must be own properties; inherited values should not
   // satisfy a schema because `struct` models object payload shape, not prototype chains.
-  entries.every(([key, guard]) => Object.hasOwn(obj, key) && guard(obj[key]))
+  entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]))
 );
 var hasValidOptionalKeys = (obj, entries) => (
   // WHY: Optional keys are validated only when present. Missing keys stay valid
   // without forcing callers to encode `undefined` into the value guard.
-  entries.every(([key, guard]) => !Object.hasOwn(obj, key) || guard(obj[key]))
+  entries.every(
+    ([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key])
+  )
 );
 var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
 function optionalKey(guard) {
@@ -378,7 +387,7 @@ function struct(schema, options) {
   const optionalEntries = [];
   const schemaKeys = [];
   for (const key in schema) {
-    if (!Object.hasOwn(schema, key)) continue;
+    if (!hasOwnPropertyKey(schema, key)) continue;
     const field = schema[key];
     schemaKeys.push(key);
     if (isOptionalSchemaField(field)) {
@@ -439,6 +448,7 @@ export {
   isDataView,
   isDate,
   isError,
+  isFile,
   isFiniteNumber,
   isFunction,
   isInfiniteNumber,
@@ -448,6 +458,7 @@ export {
   isMap,
   isNaN,
   isNegative,
+  isNil,
   isNull,
   isNumber,
   isNumberPrimitive,

package/docs/README.md

@@ -0,0 +1,101 @@
+# is-kit docs
+
+This directory contains the public documentation site for `is-kit`.
+
+The site is built with Next.js and shadcn/ui. It serves the marketing pages, hand-written API guides, and the generated TypeDoc output.
+
+## What lives here
+
+- `app/` - Next.js routes and page entry points
+- `components/` - reusable docs-site UI and page sections
+- `constants/` - site navigation and page metadata
+- `lib/` - docs-specific helpers and data shaping
+- `public/` - static assets and generated API output
+
+## Local development
+
+From the repository root:
+
+```bash
+pnpm --filter ./docs dev
+```
+
+Other common commands:
+
+```bash
+pnpm --filter ./docs build
+pnpm --filter ./docs start
+```
+
+If you use `mise`, run the same commands through `mise exec`.
+
+## Generated API reference
+
+The API reference is generated from the library source with TypeDoc and written to `docs/public/api`.
+
+From the repository root:
+
+```bash
+pnpm typedoc
+```
+
+After generation, the docs site serves that static output under `/api`.
+
+## Common editing workflow
+
+### Update a guide or landing page
+
+Edit the relevant route in `app/` and the supporting components in `components/`.
+
+### Update navigation or docs metadata
+
+Check the files under `constants/` and `lib/`.
+
+### Refresh generated API docs
+
+Run:
+
+```bash
+pnpm typedoc
+```
+
+### Add or update static assets
+
+Place them under `public/`.
+
+## shadcn/ui
+
+The docs app is already configured for shadcn/ui with the `@/*` alias.
+
+List available components:
+
+```bash
+pnpm --filter ./docs run shadcn:list
+```
+
+Add a component:
+
+```bash
+pnpm --filter ./docs run shadcn:add button
+```
+
+If you need to reinitialize shadcn:
+
+```bash
+pnpm --filter ./docs run shadcn:init
+```
+
+## Example
+
+```tsx
+import { Button } from '@/components/ui/button';
+
+export default function Example() {
+  return (
+    <div className='space-x-2'>
+      <Button>Default</Button>
+      <Button variant='secondary'>Secondary</Button>
+    </div>
+  );
+}
+```

package/docs/agent-rules.md

@@ -0,0 +1,63 @@
+# is-kit Agent Rules
+
+Copy this into a consumer repository's `AGENTS.md`, `CLAUDE.md`, or
+`.agents/rules/is-kit.md` when AI agents generate or review code that uses
+`is-kit`.
+
+## Usage Rules
+
+- Build reusable custom guards with `define<T>(...)` instead of writing
+  standalone type-predicate functions by hand.
+- Prefer `is-kit` combinators over hand-written boolean composition when
+  combining existing guards.
+- Use `or(isA, isB)` instead of `(value) => isA(value) || isB(value)` when the
+  result should be a reusable guard.
+- Use `and(baseGuard, refinement)` or `andAll(...)` instead of hand-written
+  `&&` checks when narrowing should be preserved.
+- Use `not(guard)` for reusable negated guards.
+- Use `nullable(guard)`, `optional(guard)`, or `nullish(guard)` when widening an
+  existing guard to accept `null` and/or `undefined`.
+- Use `isNil(value)` when checking a value directly for `null | undefined`.
+- Use `optionalKey(guard)` for optional object keys inside `struct`.
+
+## Preferred Examples
+
+```ts
+import {
+  and,
+  define,
+  isNil,
+  isNumber,
+  isString,
+  nullish,
+  or,
+  predicateToRefine
+} from 'is-kit';
+
+const isId = or(isString, isNumber);
+const isMaybeName = nullish(isString);
+const isSlug = define<string>(
+  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+);
+const isPositiveNumber = and(
+  isNumber,
+  predicateToRefine<number>((value) => value > 0)
+);
+
+declare const value: unknown;
+
+if (isNil(value)) {
+  return;
+}
+```
+
+## Avoid
+
+```ts
+declare const value: unknown;
+
+const isId = (value: unknown) => isString(value) || isNumber(value);
+const isMaybeName = (value: unknown) => value == null || isString(value);
+const isSlug = (value: unknown): value is string =>
+  isString(value) && /^[a-z0-9-]+$/.test(value);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "is-kit",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -22,6 +22,7 @@
   ],
   "files": [
     "dist",
+    "docs/agent-rules.md",
     "README.md",
     "LICENSE"
   ],