is-kit 1.8.2 → 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,39 @@ assert(isString, input, 'Expected a string');
 input.toUpperCase();
 ```
 
-### 8. Narrow object keys
+### 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.
+Invalid JSON and guard mismatches both return `{ valid: false }`; values are not
+coerced to satisfy the guard.
+
+```ts
+import { isString, safeJsonParse, typedStruct } from 'is-kit';
+
+type User = {
+  id: string;
+  name: string;
+};
+
+const isUser = typedStruct<User>()({
+  id: isString,
+  name: isString
+});
+
+declare const input: string;
+const result = safeJsonParse(input, isUser);
+
+if (result.valid) {
+  result.value.name.toUpperCase();
+}
+```
+
+`safeJsonParse` is a decode-then-guard helper. It does not perform schema
+coercion and does not depend on a transport or schema format such as HTTP or
+OpenAPI.
+
+### 10. Narrow object keys
 
 Use key helpers when the important part of a value is one property.
 
@@ -378,7 +435,7 @@ The library is organized around a few small building blocks:
 - **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
 - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
 - **Nullish handling**: `nullable`, `nonNull`, `nullish`, `optional`, `required`
-- **Result helpers**: `safeParse`, `safeParseWith`, `assert`
+- **Result helpers**: `safeParse`, `safeParseWith`, `safeJsonParse`, `assert`
 
 For the full API list and dedicated pages, use the docs site below.
 

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.
  *
@@ -232,6 +243,14 @@ declare function safeParse(fn: (value: unknown) => boolean, value: unknown): Par
  */
 declare function safeParseWith<T>(guard: Guard<T>): (value: unknown) => ParseResult<T>;
 declare function safeParseWith<A, B extends A>(refine: Refine<A, B>): (value: A) => ParseResult<B>;
+/**
+ * Decodes JSON text and validates the decoded value without coercion.
+ *
+ * @param input JSON text to decode.
+ * @param guard Guard used to validate the decoded `unknown` value.
+ * @returns The decoded value when valid; `{ valid: false }` for invalid JSON or a guard mismatch.
+ */
+declare function safeJsonParse<T>(input: string, guard: Predicate<T>): ParseResult<T>;
 
 /**
  * Converts a boolean predicate into a refinement preserving the input type.
@@ -645,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, 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.
  *
@@ -232,6 +243,14 @@ declare function safeParse(fn: (value: unknown) => boolean, value: unknown): Par
  */
 declare function safeParseWith<T>(guard: Guard<T>): (value: unknown) => ParseResult<T>;
 declare function safeParseWith<A, B extends A>(refine: Refine<A, B>): (value: A) => ParseResult<B>;
+/**
+ * Decodes JSON text and validates the decoded value without coercion.
+ *
+ * @param input JSON text to decode.
+ * @param guard Guard used to validate the decoded `unknown` value.
+ * @returns The decoded value when valid; `{ valid: false }` for invalid JSON or a guard mismatch.
+ */
+declare function safeJsonParse<T>(input: string, guard: Predicate<T>): ParseResult<T>;
 
 /**
  * Converts a boolean predicate into a refinement preserving the input type.
@@ -645,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, 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,
@@ -88,6 +89,7 @@ __export(index_exports, {
   predicateToRefine: () => predicateToRefine,
   recordOf: () => recordOf,
   required: () => required,
+  safeJsonParse: () => safeJsonParse,
   safeParse: () => safeParse,
   safeParseWith: () => safeParseWith,
   setOf: () => setOf,
@@ -219,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) {
@@ -317,6 +328,15 @@ function safeParse(fn, value) {
 function safeParseWith(fn) {
   return (value) => safeParse(fn, value);
 }
+function safeJsonParse(input, guard) {
+  let value;
+  try {
+    value = JSON.parse(input);
+  } catch {
+    return { valid: false };
+  }
+  return safeParse(guard, value);
+}
 
 // src/core/predicate.ts
 var predicateToRefine = (fn) => (value) => fn(value);
@@ -550,6 +570,7 @@ function tupleOf(...guards) {
   isWeakMap,
   isWeakSet,
   isZero,
+  lazy,
   mapOf,
   narrowKeyTo,
   nonEmptyArrayOf,
@@ -565,6 +586,7 @@ function tupleOf(...guards) {
   predicateToRefine,
   recordOf,
   required,
+  safeJsonParse,
   safeParse,
   safeParseWith,
   setOf,

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) {
@@ -217,6 +226,15 @@ function safeParse(fn, value) {
 function safeParseWith(fn) {
   return (value) => safeParse(fn, value);
 }
+function safeJsonParse(input, guard) {
+  let value;
+  try {
+    value = JSON.parse(input);
+  } catch {
+    return { valid: false };
+  }
+  return safeParse(guard, value);
+}
 
 // src/core/predicate.ts
 var predicateToRefine = (fn) => (value) => fn(value);
@@ -449,6 +467,7 @@ export {
   isWeakMap,
   isWeakSet,
   isZero,
+  lazy,
   mapOf,
   narrowKeyTo,
   nonEmptyArrayOf,
@@ -464,6 +483,7 @@ export {
   predicateToRefine,
   recordOf,
   required,
+  safeJsonParse,
   safeParse,
   safeParseWith,
   setOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "is-kit",
-  "version": "1.8.2",
+  "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",