is-kit 1.4.1 → 1.5.0

package/README.md

@@ -69,9 +69,9 @@ import {
   and,
   or,
   not,
+  optionalKey,
   struct,
   oneOfValues,
-  optional,
   isNumber,
   isString,
   predicateToRefine
@@ -94,7 +94,7 @@ const isUser = struct({
   id: isPositive, // number > 0
   name: isString, // string
   role: isRole, // 'admin' | 'member'
-  nickname: optional(isShortString) // string <= 3 | undefined
+  nickname: optionalKey(isShortString) // key may be absent; when present, string <= 3
 });
 
 // Use them
@@ -111,6 +111,10 @@ if (isUser(maybeUser)) {
 }
 ```
 
+Use `optionalKey(...)` for key-level optional properties in `struct`.
+Use `optional(...)` when the key exists but the value itself may be `undefined`.
+Combine them as `optionalKey(optional(guard))` when both are allowed.
+
 Composed guards stay reusable:
 `isPositive` can be used standalone or as part of a `struct` definition.
 

package/dist/index.d.mts

@@ -13,13 +13,43 @@ type ParseResult<T> = {
 };
 type GuardedOf<F> = F extends (value: unknown) => value is infer G ? G : never;
 type GuardedWithin<Fs, A> = Extract<Fs extends readonly unknown[] ? GuardedOf<Fs[number]> : never, A>;
-type Schema = Readonly<Record<string, Predicate<unknown>>>;
-type InferSchema<S extends Schema> = {
-    readonly [K in keyof S]: GuardedOf<S[K]>;
-};
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
+/**
+ * Marks a `struct` schema field as optional at the key level.
+ */
+type OptionalSchemaField<G extends Predicate<unknown>> = Readonly<{
+    optional: true;
+    guard: G;
+}>;
+/**
+ * Field accepted by `struct` schemas.
+ */
+type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
+/**
+ * Object schema consumed by `struct`.
+ */
+type Schema = Readonly<Record<string, 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> = {
+    [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K;
+}[keyof S];
+type OptionalSchemaKeys<S extends Schema> = {
+    [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<{
+    readonly [K in RequiredSchemaKeys<S>]: InferSchemaField<S[K]>;
+} & {
+    readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
+}>;
+
 /**
  * Wraps a user function as a typed predicate.
  *
@@ -323,9 +353,20 @@ declare function oneOf<A, Fs extends readonly Predicate<A>[]>(...guards: Fs): (i
  */
 declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
 
+/**
+ * Marks a struct schema field as optional at the key level.
+ *
+ * When used inside `struct`, the property may be absent. If the property exists,
+ * its value must satisfy the wrapped guard.
+ *
+ * @param guard Guard used to validate the property value when the key exists.
+ * @returns Schema field marker understood by `struct`.
+ */
+declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
 /**
  * Validates an object against a field-to-guard schema.
- * Keys in the schema are required; optionally rejects extra keys when `exact: true`.
+ * Keys in the schema are required unless wrapped with `optionalKey`; optionally
+ * rejects extra keys when `exact: true`.
  *
  * @param schema Record of property guards.
  * @param options When `{ exact: true }`, disallows properties not in `schema`.
@@ -505,4 +546,4 @@ declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <co
  */
 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 OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, 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, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, 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, 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, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };

package/dist/index.d.ts

@@ -13,13 +13,43 @@ type ParseResult<T> = {
 };
 type GuardedOf<F> = F extends (value: unknown) => value is infer G ? G : never;
 type GuardedWithin<Fs, A> = Extract<Fs extends readonly unknown[] ? GuardedOf<Fs[number]> : never, A>;
-type Schema = Readonly<Record<string, Predicate<unknown>>>;
-type InferSchema<S extends Schema> = {
-    readonly [K in keyof S]: GuardedOf<S[K]>;
-};
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
+/**
+ * Marks a `struct` schema field as optional at the key level.
+ */
+type OptionalSchemaField<G extends Predicate<unknown>> = Readonly<{
+    optional: true;
+    guard: G;
+}>;
+/**
+ * Field accepted by `struct` schemas.
+ */
+type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
+/**
+ * Object schema consumed by `struct`.
+ */
+type Schema = Readonly<Record<string, 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> = {
+    [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K;
+}[keyof S];
+type OptionalSchemaKeys<S extends Schema> = {
+    [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<{
+    readonly [K in RequiredSchemaKeys<S>]: InferSchemaField<S[K]>;
+} & {
+    readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
+}>;
+
 /**
  * Wraps a user function as a typed predicate.
  *
@@ -323,9 +353,20 @@ declare function oneOf<A, Fs extends readonly Predicate<A>[]>(...guards: Fs): (i
  */
 declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
 
+/**
+ * Marks a struct schema field as optional at the key level.
+ *
+ * When used inside `struct`, the property may be absent. If the property exists,
+ * its value must satisfy the wrapped guard.
+ *
+ * @param guard Guard used to validate the property value when the key exists.
+ * @returns Schema field marker understood by `struct`.
+ */
+declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
 /**
  * Validates an object against a field-to-guard schema.
- * Keys in the schema are required; optionally rejects extra keys when `exact: true`.
+ * Keys in the schema are required unless wrapped with `optionalKey`; optionally
+ * rejects extra keys when `exact: true`.
  *
  * @param schema Record of property guards.
  * @param options When `{ exact: true }`, disallows properties not in `schema`.
@@ -505,4 +546,4 @@ declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <co
  */
 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 OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, 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, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, 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, 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, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, struct, toBooleanPredicates, tupleOf };

package/dist/index.js

@@ -76,6 +76,7 @@ __export(index_exports, {
   oneOf: () => oneOf,
   oneOfValues: () => oneOfValues,
   optional: () => optional,
+  optionalKey: () => optionalKey,
   or: () => or,
   predicateToRefine: () => predicateToRefine,
   recordOf: () => recordOf,
@@ -219,25 +220,26 @@ var isBlob = typeof Blob !== "undefined" ? define((value) => value instanceof Bl
 var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
 
 // src/core/equals.ts
+var guardedBy = (guard) => define((input) => guard(input));
 function equals(target) {
-  return (input) => {
-    return Object.is(input, target);
-  };
+  return define((input) => Object.is(input, target));
 }
 function equalsBy(guard, selector) {
-  const createComparator = (selectorFn) => (target) => (input) => {
-    if (!guard(input)) return false;
+  const matchesGuard = guardedBy(guard);
+  const createComparator = (selectorFn) => (target) => define((input) => {
+    if (!matchesGuard(input)) return false;
     return Object.is(selectorFn(input), target);
-  };
+  });
   if (selector) {
     return createComparator(selector);
   }
-  return (selector2) => createComparator(selector2);
+  return (selectorFn) => createComparator(selectorFn);
 }
 function equalsKey(key, target) {
-  return (input) => {
+  const hasMatchingKey = define((input) => {
     return isObject(input) && Object.prototype.hasOwnProperty.call(input, key) && Object.is(input[key], target);
-  };
+  });
+  return (input) => hasMatchingKey(input);
 }
 
 // src/core/parse.ts
@@ -331,15 +333,44 @@ function recordOf(keyFunction, valueFunction) {
 }
 
 // src/core/combinators/struct.ts
-var hasRequiredKeys = (obj, schema, keys) => keys.every((key) => key in obj && schema[key](obj[key]));
+var hasOwnKey = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+var isOptionalSchemaField = define(
+  // WHY: Optional fields are represented as a small tagged object so `struct`
+  // can distinguish schema metadata from plain predicate functions up front.
+  (field) => isObject(field) && field.optional === true && typeof field.guard === "function"
+);
+var hasRequiredKeys = (obj, entries) => (
+  // WHY: Required fields must be own properties; inherited values should not
+  // satisfy a schema because `struct` models object payload shape, not prototype chains.
+  entries.every(([key, guard]) => hasOwnKey(obj, key) && guard(obj[key]))
+);
+var hasValidOptionalKeys = (obj, entries) => (
+  // WHY: Optional keys are validated only when present. Missing keys stay valid
+  // without forcing callers to encode `undefined` into the value guard.
+  entries.every(([key, guard]) => !hasOwnKey(obj, key) || guard(obj[key]))
+);
 var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
+function optionalKey(guard) {
+  return { optional: true, guard };
+}
 function struct(schema, options) {
-  const schemaKeys = Object.keys(schema);
+  const requiredEntries = [];
+  const optionalEntries = [];
+  const schemaKeys = [];
+  for (const [key, field] of Object.entries(schema)) {
+    schemaKeys.push(key);
+    if (isOptionalSchemaField(field)) {
+      optionalEntries.push([key, field.guard]);
+      continue;
+    }
+    requiredEntries.push([key, field]);
+  }
   const allowed = options?.exact ? new Set(schemaKeys) : null;
   return (input) => {
     if (!isPlainObject(input)) return false;
     const obj = input;
-    if (!hasRequiredKeys(obj, schema, schemaKeys)) return false;
+    if (!hasRequiredKeys(obj, requiredEntries)) return false;
+    if (!hasValidOptionalKeys(obj, optionalEntries)) return false;
     if (!allowed) return true;
     return hasOnlyAllowedKeys(obj, allowed);
   };
@@ -462,6 +493,7 @@ function narrowKeyTo(guard, key) {
   oneOf,
   oneOfValues,
   optional,
+  optionalKey,
   or,
   predicateToRefine,
   recordOf,

package/dist/index.mjs

@@ -129,25 +129,26 @@ var isBlob = typeof Blob !== "undefined" ? define((value) => value instanceof Bl
 var isInstanceOf = (constructor) => define((value) => value instanceof constructor);
 
 // src/core/equals.ts
+var guardedBy = (guard) => define((input) => guard(input));
 function equals(target) {
-  return (input) => {
-    return Object.is(input, target);
-  };
+  return define((input) => Object.is(input, target));
 }
 function equalsBy(guard, selector) {
-  const createComparator = (selectorFn) => (target) => (input) => {
-    if (!guard(input)) return false;
+  const matchesGuard = guardedBy(guard);
+  const createComparator = (selectorFn) => (target) => define((input) => {
+    if (!matchesGuard(input)) return false;
     return Object.is(selectorFn(input), target);
-  };
+  });
   if (selector) {
     return createComparator(selector);
   }
-  return (selector2) => createComparator(selector2);
+  return (selectorFn) => createComparator(selectorFn);
 }
 function equalsKey(key, target) {
-  return (input) => {
+  const hasMatchingKey = define((input) => {
     return isObject(input) && Object.prototype.hasOwnProperty.call(input, key) && Object.is(input[key], target);
-  };
+  });
+  return (input) => hasMatchingKey(input);
 }
 
 // src/core/parse.ts
@@ -241,15 +242,44 @@ function recordOf(keyFunction, valueFunction) {
 }
 
 // src/core/combinators/struct.ts
-var hasRequiredKeys = (obj, schema, keys) => keys.every((key) => key in obj && schema[key](obj[key]));
+var hasOwnKey = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+var isOptionalSchemaField = define(
+  // WHY: Optional fields are represented as a small tagged object so `struct`
+  // can distinguish schema metadata from plain predicate functions up front.
+  (field) => isObject(field) && field.optional === true && typeof field.guard === "function"
+);
+var hasRequiredKeys = (obj, entries) => (
+  // WHY: Required fields must be own properties; inherited values should not
+  // satisfy a schema because `struct` models object payload shape, not prototype chains.
+  entries.every(([key, guard]) => hasOwnKey(obj, key) && guard(obj[key]))
+);
+var hasValidOptionalKeys = (obj, entries) => (
+  // WHY: Optional keys are validated only when present. Missing keys stay valid
+  // without forcing callers to encode `undefined` into the value guard.
+  entries.every(([key, guard]) => !hasOwnKey(obj, key) || guard(obj[key]))
+);
 var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
+function optionalKey(guard) {
+  return { optional: true, guard };
+}
 function struct(schema, options) {
-  const schemaKeys = Object.keys(schema);
+  const requiredEntries = [];
+  const optionalEntries = [];
+  const schemaKeys = [];
+  for (const [key, field] of Object.entries(schema)) {
+    schemaKeys.push(key);
+    if (isOptionalSchemaField(field)) {
+      optionalEntries.push([key, field.guard]);
+      continue;
+    }
+    requiredEntries.push([key, field]);
+  }
   const allowed = options?.exact ? new Set(schemaKeys) : null;
   return (input) => {
     if (!isPlainObject(input)) return false;
     const obj = input;
-    if (!hasRequiredKeys(obj, schema, schemaKeys)) return false;
+    if (!hasRequiredKeys(obj, requiredEntries)) return false;
+    if (!hasValidOptionalKeys(obj, optionalEntries)) return false;
     if (!allowed) return true;
     return hasOnlyAllowedKeys(obj, allowed);
   };
@@ -371,6 +401,7 @@ export {
   oneOf,
   oneOfValues,
   optional,
+  optionalKey,
   or,
   predicateToRefine,
   recordOf,

package/package.json

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