is-kit 1.7.4 → 1.8.0

package/README.md

@@ -309,22 +309,33 @@ if (isAdmin(value)) {
 
 Here are the kinds of problems `is-kit` is especially good at solving:
 
-### API response checks
+### Typed object guard checks
 
 ```ts
-import { isNumber, isString, safeParse, struct } from 'is-kit';
+import { isNumber, isString, optionalKey, safeParse, typedStruct } from 'is-kit';
 
-const isPost = struct({
+type PostResponse = ApiResponse<'/posts/{id}', 'get'>;
+
+const isPost = typedStruct<PostResponse>()({
   id: isNumber,
-  title: isString
+  title: isString,
+  summary: optionalKey(isString)
 });
 
+const payload: unknown = await fetchPost();
 const parsed = safeParse(isPost, payload);
+
 if (parsed.valid) {
   renderPost(parsed.value);
 }
 ```
 
+`typedStruct<T>()` is a small helper for keeping hand-written `struct` guards in
+sync with an existing object type. Optional keys in `T` must still be declared
+with `optionalKey(...)`; this makes drift visible when the target type changes.
+OpenAPI-generated response types are one useful case, but the helper is not an
+OpenAPI validator or schema generator.
+
 ### Safe array filtering
 
 ```ts

package/dist/index.d.mts

@@ -31,7 +31,7 @@ type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
  * Object schema consumed by `struct`.
  */
 type Schema = Readonly<Record<string, SchemaField>>;
-type Simplify<T> = {
+type Simplify$1<T> = {
     [K in keyof T]: T[K];
 };
 type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
@@ -44,7 +44,7 @@ type OptionalSchemaKeys<S extends Schema> = {
 /**
  * Infers the readonly object type produced by a `struct` schema.
  */
-type InferSchema<S extends Schema> = Simplify<{
+type InferSchema<S extends Schema> = Simplify$1<{
     readonly [K in RequiredSchemaKeys<S>]: InferSchemaField<S[K]>;
 } & {
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
@@ -553,6 +553,34 @@ declare function struct<S extends Schema>(schema: S, options?: {
     exact?: boolean;
 }): Predicate<InferSchema<S>>;
 
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+type StringKeyOf<T> = Extract<keyof T, string>;
+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 TypedStructTarget<T extends object> = Simplify<Readonly<Pick<T, StringKeyOf<T>>>>;
+/**
+ * Creates a `struct` builder checked against an existing object type.
+ * Optional target keys must also be declared with `optionalKey` so type drift
+ * stays visible when the target type changes.
+ *
+ * @returns Builder that rejects missing, extra, or incompatible struct fields.
+ */
+declare function typedStruct<T extends object>(): <const S extends TypedStructShape<T>>(fields: NoExtraKeys<S, TypedStructShape<T>>, options?: {
+    exact?: boolean;
+}) => Predicate<TypedStructTarget<T>>;
+
 /**
  * Validates a fixed-length tuple by applying element-wise guards.
  *
@@ -614,4 +642,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 };
+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 };

package/dist/index.d.ts

@@ -31,7 +31,7 @@ type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
  * Object schema consumed by `struct`.
  */
 type Schema = Readonly<Record<string, SchemaField>>;
-type Simplify<T> = {
+type Simplify$1<T> = {
     [K in keyof T]: T[K];
 };
 type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
@@ -44,7 +44,7 @@ type OptionalSchemaKeys<S extends Schema> = {
 /**
  * Infers the readonly object type produced by a `struct` schema.
  */
-type InferSchema<S extends Schema> = Simplify<{
+type InferSchema<S extends Schema> = Simplify$1<{
     readonly [K in RequiredSchemaKeys<S>]: InferSchemaField<S[K]>;
 } & {
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
@@ -553,6 +553,34 @@ declare function struct<S extends Schema>(schema: S, options?: {
     exact?: boolean;
 }): Predicate<InferSchema<S>>;
 
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+type StringKeyOf<T> = Extract<keyof T, string>;
+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 TypedStructTarget<T extends object> = Simplify<Readonly<Pick<T, StringKeyOf<T>>>>;
+/**
+ * Creates a `struct` builder checked against an existing object type.
+ * Optional target keys must also be declared with `optionalKey` so type drift
+ * stays visible when the target type changes.
+ *
+ * @returns Builder that rejects missing, extra, or incompatible struct fields.
+ */
+declare function typedStruct<T extends object>(): <const S extends TypedStructShape<T>>(fields: NoExtraKeys<S, TypedStructShape<T>>, options?: {
+    exact?: boolean;
+}) => Predicate<TypedStructTarget<T>>;
+
 /**
  * Validates a fixed-length tuple by applying element-wise guards.
  *
@@ -614,4 +642,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 };
+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 };

package/dist/index.js

@@ -93,7 +93,8 @@ __export(index_exports, {
   setOf: () => setOf,
   struct: () => struct,
   toBooleanPredicates: () => toBooleanPredicates,
-  tupleOf: () => tupleOf
+  tupleOf: () => tupleOf,
+  typedStruct: () => typedStruct
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -477,6 +478,15 @@ function struct(schema, options) {
   });
 }
 
+// src/core/combinators/typed-struct.ts
+function typedStruct() {
+  return (fields, options) => (
+    // WHY: `typedStruct` keeps `struct` runtime behavior while using the target
+    // type only to check that hand-written guard fields stay in sync.
+    struct(fields, options)
+  );
+}
+
 // src/core/combinators/tuple.ts
 function tupleOf(...guards) {
   return define(
@@ -558,5 +568,6 @@ function tupleOf(...guards) {
   setOf,
   struct,
   toBooleanPredicates,
-  tupleOf
+  tupleOf,
+  typedStruct
 });

package/dist/index.mjs

@@ -378,6 +378,15 @@ function struct(schema, options) {
   });
 }
 
+// src/core/combinators/typed-struct.ts
+function typedStruct() {
+  return (fields, options) => (
+    // WHY: `typedStruct` keeps `struct` runtime behavior while using the target
+    // type only to check that hand-written guard fields stay in sync.
+    struct(fields, options)
+  );
+}
+
 // src/core/combinators/tuple.ts
 function tupleOf(...guards) {
   return define(
@@ -458,5 +467,6 @@ export {
   setOf,
   struct,
   toBooleanPredicates,
-  tupleOf
+  tupleOf,
+  typedStruct
 };

package/package.json

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