is-kit 1.8.1 → 1.9.0

package/README.md

@@ -186,7 +186,9 @@ const isConfig = struct({
 
 `optionalKey(guard)` means the property may be missing.
 
-Use `struct(schema, { exact: true })` when extra keys should be rejected.
+Use `struct(schema, { exact: true })` when extra own enumerable string keys
+should be rejected. Exact mode follows `Object.keys(...)` semantics, so symbol
+keys and non-enumerable properties are outside its key matching.
 
 If the property must exist but the value may be `undefined`, use `optional(guard)` instead.
 
@@ -262,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.
 
@@ -312,7 +346,13 @@ Here are the kinds of problems `is-kit` is especially good at solving:
 ### Typed object guard checks
 
 ```ts
-import { isNumber, isString, optionalKey, safeParse, typedStruct } from 'is-kit';
+import {
+  isNumber,
+  isString,
+  optionalKey,
+  safeParse,
+  typedStruct
+} from 'is-kit';
 
 type PostResponse = ApiResponse<'/posts/{id}', 'get'>;
 
@@ -370,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.
@@ -552,7 +560,8 @@ declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSc
  * rejects extra keys when `exact: true`.
  *
  * @param schema Record of property guards.
- * @param options When `{ exact: true }`, disallows properties not in `schema`.
+ * @param options When `{ exact: true }`, disallows own enumerable string-key
+ * properties not in `schema`.
  * @returns Predicate that narrows to the inferred struct type.
  */
 declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
@@ -644,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.
@@ -552,7 +560,8 @@ declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSc
  * rejects extra keys when `exact: true`.
  *
  * @param schema Record of property guards.
- * @param options When `{ exact: true }`, disallows properties not in `schema`.
+ * @param options When `{ exact: true }`, disallows own enumerable string-key
+ * properties not in `schema`.
  * @returns Predicate that narrows to the inferred struct type.
  */
 declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
@@ -644,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.1",
+  "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",
@@ -38,20 +38,21 @@
   "license": "MIT",
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "jest": "^30.0.5",
-    "lefthook": "^2.0.13",
-    "oxfmt": "^0.52.0",
-    "oxlint": "^1.67.0",
-    "ts-jest": "^29.4.1",
+    "jest": "^30.4.2",
+    "lefthook": "^2.1.9",
+    "oxfmt": "^0.55.0",
+    "oxlint": "^1.70.0",
+    "ts-jest": "^29.4.11",
     "tsd": "^0.33.0",
     "tsup": "^8.5.0",
-    "typedoc": "^0.28.12",
-    "typescript": "^5.9.2"
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3"
   },
   "tsd": {
     "directory": "tests-d",
     "compilerOptions": {
-      "baseUrl": "."
+      "baseUrl": ".",
+      "ignoreDeprecations": "6.0"
     }
   },
   "scripts": {