is-kit 1.9.0 → 1.10.0

package/README.md

@@ -116,6 +116,7 @@ This is the core idea of `is-kit`:
 If you are new to the library, these are the pieces to remember:
 
 - `define<T>(fn)` turns a boolean check into a typed guard.
+- `lazy(factory)` defers a guard definition so recursive structures can refer to themselves.
 - `predicateToRefine(fn)` upgrades an existing predicate so it can participate in narrowing chains.
 - `struct({...})` builds an object-shape guard.
 - `safeParse(guard, value)` gives you a small tagged result object.
@@ -224,7 +225,31 @@ import { oneOfValues } from 'is-kit';
 const isStatus = oneOfValues('draft', 'published', 'archived');
 ```
 
-### 6. Handle null and undefined explicitly
+### 6. Validate recursive structures
+
+Use `lazy` when a guard needs to refer to itself. The factory runs on first use,
+and the resulting guard is cached.
+
+```ts
+import { arrayOf, isString, lazy, typedStruct } from 'is-kit';
+import type { Predicate } from 'is-kit';
+
+type Tree = {
+  readonly value: string;
+  readonly children: readonly Tree[];
+};
+
+const isTree: Predicate<Tree> = lazy(() =>
+  typedStruct<Tree>()({
+    value: isString,
+    children: arrayOf(isTree)
+  })
+);
+```
+
+`lazy` does not detect circular references in the input value.
+
+### 7. Handle null and undefined explicitly
 
 Use the nullish helpers to say exactly what is allowed.
 
@@ -245,7 +270,7 @@ const isDefinedString = required(optional(isString));
 const isNonNullString = nonNull(nullable(isString));
 ```
 
-### 7. Parse or assert unknown input
+### 8. Parse or assert unknown input
 
 Use `safeParse` when you want a result object, and `assert` when invalid data should stop execution.
 
@@ -264,7 +289,7 @@ assert(isString, input, 'Expected a string');
 input.toUpperCase();
 ```
 
-### 8. Decode and validate JSON input
+### 9. Decode and validate JSON input
 
 Use `safeJsonParse` at a JSON text boundary. It decodes the text, treats the
 result as `unknown`, and only returns the value after the guard accepts it.
@@ -296,7 +321,7 @@ if (result.valid) {
 coercion and does not depend on a transport or schema format such as HTTP or
 OpenAPI.
 
-### 9. Narrow object keys
+### 10. Narrow object keys
 
 Use key helpers when the important part of a value is one property.
 

package/dist/index.d.mts

@@ -133,6 +133,17 @@ declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]
  */
 declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => Predicate<A & Record<K, T>>;
 
+/**
+ * Creates a predicate whose implementation is initialized on first use.
+ *
+ * The initialized predicate is cached after the factory returns successfully.
+ * Circular references in the input value are not detected.
+ *
+ * @param factory Function that creates the predicate when it is first evaluated.
+ * @returns Predicate that delegates to the lazily initialized implementation.
+ */
+declare function lazy<T>(factory: () => Predicate<T>): Predicate<T>;
+
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
  *
@@ -653,4 +664,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, 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, 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 };

package/dist/index.d.ts

@@ -133,6 +133,17 @@ declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]
  */
 declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => Predicate<A & Record<K, T>>;
 
+/**
+ * Creates a predicate whose implementation is initialized on first use.
+ *
+ * The initialized predicate is cached after the factory returns successfully.
+ * Circular references in the input value are not detected.
+ *
+ * @param factory Function that creates the predicate when it is first evaluated.
+ * @returns Predicate that delegates to the lazily initialized implementation.
+ */
+declare function lazy<T>(factory: () => Predicate<T>): Predicate<T>;
+
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
  *
@@ -653,4 +664,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, 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, 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 };

package/dist/index.js

@@ -73,6 +73,7 @@ __export(index_exports, {
   isWeakMap: () => isWeakMap,
   isWeakSet: () => isWeakSet,
   isZero: () => isZero,
+  lazy: () => lazy,
   mapOf: () => mapOf,
   narrowKeyTo: () => narrowKeyTo,
   nonEmptyArrayOf: () => nonEmptyArrayOf,
@@ -220,6 +221,15 @@ function narrowKeyTo(guard, key) {
   };
 }
 
+// src/core/lazy.ts
+function lazy(factory) {
+  let predicate;
+  return (value) => {
+    predicate ??= factory();
+    return predicate(value);
+  };
+}
+
 // src/utils/guard-collections.ts
 var everyArrayValue = (values, predicate) => {
   for (const value of values) {
@@ -560,6 +570,7 @@ function tupleOf(...guards) {
   isWeakMap,
   isWeakSet,
   isZero,
+  lazy,
   mapOf,
   narrowKeyTo,
   nonEmptyArrayOf,

package/dist/index.mjs

@@ -119,6 +119,15 @@ function narrowKeyTo(guard, key) {
   };
 }
 
+// src/core/lazy.ts
+function lazy(factory) {
+  let predicate;
+  return (value) => {
+    predicate ??= factory();
+    return predicate(value);
+  };
+}
+
 // src/utils/guard-collections.ts
 var everyArrayValue = (values, predicate) => {
   for (const value of values) {
@@ -458,6 +467,7 @@ export {
   isWeakMap,
   isWeakSet,
   isZero,
+  lazy,
   mapOf,
   narrowKeyTo,
   nonEmptyArrayOf,

package/package.json

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