is-kit 1.11.0 → 1.11.2

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:

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>;
@@ -55,6 +63,34 @@ type InferSchema<S extends SchemaShape<S>> = Simplify<{
 } & {
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
 }>;
+/**
+ * Extracts optional keys from an object type.
+ */
+type OptionalObjectKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+/**
+ * Extracts required keys from an object type.
+ */
+type RequiredObjectKeys<T> = Exclude<keyof T, OptionalObjectKeys<T>>;
+/**
+ * Schema shape checked against an existing object type by `typedStruct`.
+ */
+type TypedStructShape<T extends object> = {
+    readonly [K in Extract<RequiredObjectKeys<T>, string>]-?: Predicate<T[K]>;
+} & {
+    readonly [K in Extract<OptionalObjectKeys<T>, string>]-?: OptionalSchemaField<Predicate<T[K]>>;
+};
+/**
+ * Keeps a schema type while rejecting keys outside the expected shape.
+ */
+type NoExtraKeys<S, Shape> = S & {
+    readonly [K in Exclude<keyof S, keyof Shape>]: never;
+};
+/**
+ * Field set accepted by `typedStruct` for a target object type.
+ */
+type TypedStructFields<T extends object, S extends TypedStructShape<T>> = NoExtraKeys<S, TypedStructShape<T>>;
 
 /**
  * Asserts that a value satisfies a guard or refinement, otherwise throws.
@@ -69,12 +105,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 +188,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 +266,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 +301,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,17 +433,21 @@ declare const isSymbol: Predicate<symbol>;
 /**
  * Checks whether a value is exactly `undefined`.
  *
- * To accept `null` as well, use {@link isNil}.
+ * 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`.
  *
- * To accept `undefined` as well, use {@link isNil}.
+ * 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>;
 /**
@@ -604,19 +690,6 @@ declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
     exact?: boolean;
 }): Predicate<InferSchema<S>>;
 
-type OptionalKeys<T> = {
-    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
-}[keyof T];
-type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;
-type TypedStructShape<T extends object> = {
-    readonly [K in Extract<RequiredKeys<T>, string>]-?: Predicate<T[K]>;
-} & {
-    readonly [K in Extract<OptionalKeys<T>, string>]-?: OptionalSchemaField<Predicate<T[K]>>;
-};
-type NoExtraKeys<S, Shape> = S & {
-    readonly [K in Exclude<keyof S, keyof Shape>]: never;
-};
-type TypedStructFields<T extends object, S extends TypedStructShape<T>> = NoExtraKeys<S, TypedStructShape<T>>;
 /**
  * Creates a `struct` builder checked against an existing object type.
  * Optional target keys must also be declared with `optionalKey` so type drift
@@ -690,4 +763,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, 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 };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type TypedStructFields, type TypedStructShape, 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>;
@@ -55,6 +63,34 @@ type InferSchema<S extends SchemaShape<S>> = Simplify<{
 } & {
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
 }>;
+/**
+ * Extracts optional keys from an object type.
+ */
+type OptionalObjectKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+/**
+ * Extracts required keys from an object type.
+ */
+type RequiredObjectKeys<T> = Exclude<keyof T, OptionalObjectKeys<T>>;
+/**
+ * Schema shape checked against an existing object type by `typedStruct`.
+ */
+type TypedStructShape<T extends object> = {
+    readonly [K in Extract<RequiredObjectKeys<T>, string>]-?: Predicate<T[K]>;
+} & {
+    readonly [K in Extract<OptionalObjectKeys<T>, string>]-?: OptionalSchemaField<Predicate<T[K]>>;
+};
+/**
+ * Keeps a schema type while rejecting keys outside the expected shape.
+ */
+type NoExtraKeys<S, Shape> = S & {
+    readonly [K in Exclude<keyof S, keyof Shape>]: never;
+};
+/**
+ * Field set accepted by `typedStruct` for a target object type.
+ */
+type TypedStructFields<T extends object, S extends TypedStructShape<T>> = NoExtraKeys<S, TypedStructShape<T>>;
 
 /**
  * Asserts that a value satisfies a guard or refinement, otherwise throws.
@@ -69,12 +105,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 +188,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 +266,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 +301,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,17 +433,21 @@ declare const isSymbol: Predicate<symbol>;
 /**
  * Checks whether a value is exactly `undefined`.
  *
- * To accept `null` as well, use {@link isNil}.
+ * 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`.
  *
- * To accept `undefined` as well, use {@link isNil}.
+ * 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>;
 /**
@@ -604,19 +690,6 @@ declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
     exact?: boolean;
 }): Predicate<InferSchema<S>>;
 
-type OptionalKeys<T> = {
-    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
-}[keyof T];
-type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;
-type TypedStructShape<T extends object> = {
-    readonly [K in Extract<RequiredKeys<T>, string>]-?: Predicate<T[K]>;
-} & {
-    readonly [K in Extract<OptionalKeys<T>, string>]-?: OptionalSchemaField<Predicate<T[K]>>;
-};
-type NoExtraKeys<S, Shape> = S & {
-    readonly [K in Exclude<keyof S, keyof Shape>]: never;
-};
-type TypedStructFields<T extends object, S extends TypedStructShape<T>> = NoExtraKeys<S, TypedStructShape<T>>;
 /**
  * Creates a `struct` builder checked against an existing object type.
  * Optional target keys must also be declared with `optionalKey` so type drift
@@ -690,4 +763,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, 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 };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type TypedStructFields, type TypedStructShape, 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

@@ -114,6 +114,10 @@ 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) {
@@ -237,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) {
@@ -469,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) {
@@ -485,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)) {

package/dist/index.mjs

@@ -10,6 +10,10 @@ 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) {
@@ -133,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) {
@@ -365,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) {
@@ -381,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)) {

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.11.0",
+  "version": "1.11.2",
   "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"
   ],