is-kit 1.8.2 → 1.9.0

package/README.md

@@ -264,7 +264,39 @@ assert(isString, input, 'Expected a string');
 input.toUpperCase();
 ```
 
-### 8. Narrow object keys
+### 8. 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.
+
+### 9. Narrow object keys
 
 Use key helpers when the important part of a value is one property.
 
@@ -378,7 +410,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

@@ -232,6 +232,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 +653,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, 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

@@ -232,6 +232,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 +653,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, 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

@@ -88,6 +88,7 @@ __export(index_exports, {
   predicateToRefine: () => predicateToRefine,
   recordOf: () => recordOf,
   required: () => required,
+  safeJsonParse: () => safeJsonParse,
   safeParse: () => safeParse,
   safeParseWith: () => safeParseWith,
   setOf: () => setOf,
@@ -317,6 +318,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);
@@ -565,6 +575,7 @@ function tupleOf(...guards) {
   predicateToRefine,
   recordOf,
   required,
+  safeJsonParse,
   safeParse,
   safeParseWith,
   setOf,

package/dist/index.mjs

@@ -217,6 +217,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);
@@ -464,6 +473,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.9.0",
   "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",