is-kit 1.7.4 → 1.8.1

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,20 +31,26 @@ type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
  * Object schema consumed by `struct`.
  */
 type Schema = Readonly<Record<string, SchemaField>>;
+/**
+ * Object schema shape preserving concrete keys.
+ */
+type SchemaShape<S extends object> = Readonly<{
+    [K in keyof S]: SchemaField;
+}>;
 type Simplify<T> = {
     [K in keyof T]: T[K];
 };
 type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
-type RequiredSchemaKeys<S extends Schema> = {
+type RequiredSchemaKeys<S extends SchemaShape<S>> = {
     [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K;
 }[keyof S];
-type OptionalSchemaKeys<S extends Schema> = {
+type OptionalSchemaKeys<S extends SchemaShape<S>> = {
     [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? K : never;
 }[keyof S];
 /**
  * Infers the readonly object type produced by a `struct` schema.
  */
-type InferSchema<S extends Schema> = Simplify<{
+type InferSchema<S extends SchemaShape<S>> = Simplify<{
     readonly [K in RequiredSchemaKeys<S>]: InferSchemaField<S[K]>;
 } & {
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
@@ -549,10 +555,34 @@ declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSc
  * @param options When `{ exact: true }`, disallows properties not in `schema`.
  * @returns Predicate that narrows to the inferred struct type.
  */
-declare function struct<S extends Schema>(schema: S, options?: {
+declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
     exact?: boolean;
 }): Predicate<InferSchema<S>>;
 
+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 TypedStructFields<T extends object, S extends TypedStructShape<T>> = NoExtraKeys<S, TypedStructShape<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: TypedStructFields<T, S>, options?: {
+    exact?: boolean;
+}) => Predicate<InferSchema<TypedStructFields<T, S>>>;
+
 /**
  * Validates a fixed-length tuple by applying element-wise guards.
  *
@@ -614,4 +644,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,20 +31,26 @@ type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
  * Object schema consumed by `struct`.
  */
 type Schema = Readonly<Record<string, SchemaField>>;
+/**
+ * Object schema shape preserving concrete keys.
+ */
+type SchemaShape<S extends object> = Readonly<{
+    [K in keyof S]: SchemaField;
+}>;
 type Simplify<T> = {
     [K in keyof T]: T[K];
 };
 type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
-type RequiredSchemaKeys<S extends Schema> = {
+type RequiredSchemaKeys<S extends SchemaShape<S>> = {
     [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K;
 }[keyof S];
-type OptionalSchemaKeys<S extends Schema> = {
+type OptionalSchemaKeys<S extends SchemaShape<S>> = {
     [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? K : never;
 }[keyof S];
 /**
  * Infers the readonly object type produced by a `struct` schema.
  */
-type InferSchema<S extends Schema> = Simplify<{
+type InferSchema<S extends SchemaShape<S>> = Simplify<{
     readonly [K in RequiredSchemaKeys<S>]: InferSchemaField<S[K]>;
 } & {
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
@@ -549,10 +555,34 @@ declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSc
  * @param options When `{ exact: true }`, disallows properties not in `schema`.
  * @returns Predicate that narrows to the inferred struct type.
  */
-declare function struct<S extends Schema>(schema: S, options?: {
+declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
     exact?: boolean;
 }): Predicate<InferSchema<S>>;
 
+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 TypedStructFields<T extends object, S extends TypedStructShape<T>> = NoExtraKeys<S, TypedStructShape<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: TypedStructFields<T, S>, options?: {
+    exact?: boolean;
+}) => Predicate<InferSchema<TypedStructFields<T, S>>>;
+
 /**
  * Validates a fixed-length tuple by applying element-wise guards.
  *
@@ -614,4 +644,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);
 
@@ -458,7 +459,9 @@ function struct(schema, options) {
   const requiredEntries = [];
   const optionalEntries = [];
   const schemaKeys = [];
-  for (const [key, field] of Object.entries(schema)) {
+  for (const key in schema) {
+    if (!Object.hasOwn(schema, key)) continue;
+    const field = schema[key];
     schemaKeys.push(key);
     if (isOptionalSchemaField(field)) {
       optionalEntries.push([key, field.guard]);
@@ -477,6 +480,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 +570,6 @@ function tupleOf(...guards) {
   setOf,
   struct,
   toBooleanPredicates,
-  tupleOf
+  tupleOf,
+  typedStruct
 });

package/dist/index.mjs

@@ -359,7 +359,9 @@ function struct(schema, options) {
   const requiredEntries = [];
   const optionalEntries = [];
   const schemaKeys = [];
-  for (const [key, field] of Object.entries(schema)) {
+  for (const key in schema) {
+    if (!Object.hasOwn(schema, key)) continue;
+    const field = schema[key];
     schemaKeys.push(key);
     if (isOptionalSchemaField(field)) {
       optionalEntries.push([key, field.guard]);
@@ -378,6 +380,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 +469,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.1",
   "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",