typebox 1.0.8 → 1.0.10

package/build/schema/engine/_exact_optional.d.mts

@@ -0,0 +1,3 @@
+export declare function IsExactOptional(required: string[], key: string): boolean;
+export declare function InexactOptionalBuild(value: string, key: string): string;
+export declare function InexactOptionalCheck(value: Record<PropertyKey, unknown>, key: string): boolean;

package/build/schema/engine/_exact_optional.mjs

@@ -0,0 +1,20 @@
+import { Settings } from '../../system/settings/index.mjs';
+import { EmitGuard as E, Guard as G } from '../../guard/index.mjs';
+// ------------------------------------------------------------------
+// IsExactOptional
+// ------------------------------------------------------------------
+export function IsExactOptional(required, key) {
+    return required.includes(key) || Settings.Get().exactOptionalPropertyTypes;
+}
+// ------------------------------------------------------------------
+// ExactOptionalBuild
+// ------------------------------------------------------------------
+export function InexactOptionalBuild(value, key) {
+    return E.IsUndefined(E.Member(value, key));
+}
+// ------------------------------------------------------------------
+// ExactOptionalCheck
+// ------------------------------------------------------------------
+export function InexactOptionalCheck(value, key) {
+    return G.IsUndefined(value[key]);
+}

package/build/schema/engine/properties.mjs

@@ -2,6 +2,7 @@
 import { Guard as G, EmitGuard as E } from '../../guard/index.mjs';
 import * as S from '../types/index.mjs';
 import { BuildSchema, CheckSchema, ErrorSchema } from './schema.mjs';
+import { InexactOptionalCheck, InexactOptionalBuild, IsExactOptional } from './_exact_optional.mjs';
 // ------------------------------------------------------------------
 // Build
 // ------------------------------------------------------------------
@@ -11,9 +12,35 @@ export function BuildProperties(context, schema, value) {
         const notKey = E.Not(E.HasPropertyKey(value, E.Constant(key)));
         const isSchema = BuildSchema(context, schema, E.Member(value, key));
         const addKey = context.AddKey(E.Constant(key));
-        // optimization: E.Or(notKey, E.And(isSchema, addKey))
         const guarded = context.UseUnevaluated() ? E.And(isSchema, addKey) : isSchema;
-        return !required.includes(key) ? E.Or(notKey, guarded) : guarded;
+        // --------------------------------------------------------------
+        // Optimization
+        //
+        // If a key is required, we can skip the `notKey` check since this
+        // condition is already enforced by Required. This optimization is
+        // only valid when Required is evaluated before Properties.
+        //
+        // --------------------------------------------------------------
+        const isProperty = required.includes(key) ? guarded : E.Or(notKey, guarded);
+        // --------------------------------------------------------------
+        // ExactOptionalProperties
+        //
+        // By default, TypeScript allows optional properties to be assigned
+        // undefined. This is a bit misleading, since 'optional' is usually
+        // understood to mean 'the key may be absent', not 'the key may be
+        // present with an undefined value'.
+        //
+        // The 'IsExactOptional' check returns false by default, matching
+        // TypeScript's behavior. When exactOptionalPropertyTypes is enabled
+        // in tsconfig.json, TypeBox can be configured to use the stricter 
+        // semantics via System settings:
+        //
+        //   Settings.Set({ exactOptionalPropertyTypes: true })
+        //
+        // --------------------------------------------------------------
+        return IsExactOptional(required, key)
+            ? isProperty
+            : E.Or(InexactOptionalBuild(value, key), isProperty);
     });
     return E.ReduceAnd(everyKey);
 }
@@ -21,9 +48,12 @@ export function BuildProperties(context, schema, value) {
 // Check
 // ------------------------------------------------------------------
 export function CheckProperties(context, schema, value) {
+    const required = S.IsRequired(schema) ? schema.required : [];
     const isProperties = G.Every(G.Entries(schema.properties), ([key, schema]) => {
-        return !G.HasPropertyKey(value, key)
-            || (CheckSchema(context, schema, value[key]) && context.AddKey(key));
+        const isProperty = !G.HasPropertyKey(value, key) || (CheckSchema(context, schema, value[key]) && context.AddKey(key));
+        return IsExactOptional(required, key)
+            ? isProperty
+            : InexactOptionalCheck(value, key) || isProperty;
     });
     return isProperties;
 }
@@ -31,11 +61,15 @@ export function CheckProperties(context, schema, value) {
 // Error
 // ------------------------------------------------------------------
 export function ErrorProperties(context, schemaPath, instancePath, schema, value) {
+    const required = S.IsRequired(schema) ? schema.required : [];
     const isProperties = G.EveryAll(G.Entries(schema.properties), ([key, schema]) => {
         const nextSchemaPath = `${schemaPath}/properties/${key}`;
         const nextInstancePath = `${instancePath}/${key}`;
-        return !G.HasPropertyKey(value, key)
-            || (ErrorSchema(context, nextSchemaPath, nextInstancePath, schema, value[key]) && context.AddKey(key));
+        // Defer error generation for IsExactOptional
+        const isProperty = () => (!G.HasPropertyKey(value, key) || (ErrorSchema(context, nextSchemaPath, nextInstancePath, schema, value[key]) && context.AddKey(key)));
+        return IsExactOptional(required, key)
+            ? isProperty()
+            : InexactOptionalCheck(value, key) || isProperty();
     });
     return isProperties;
 }

package/build/system/settings/settings.d.mts

@@ -23,6 +23,16 @@ export interface TSettings {
      * @default true
      */
     useEval: boolean;
+    /**
+     * Enables or disables 'exactOptionalPropertyTypes' check semantics. By default, TypeScript
+     * allows optional properties to be assigned 'undefined'. While this behavior differs from the
+     * common interpretation of 'optional' as meaning 'key may be absent', TypeBox adopts the default
+     * TypeScript semantics to remain consistent with the language. This option is provided to align
+     * runtime check semantics with projects that configure 'exactOptionalPropertyTypes: true' in
+     * tsconfig.json.
+     * @default false
+     */
+    exactOptionalPropertyTypes: boolean;
     /**
      * Controls whether internal compositor properties (`~kind`, `~readonly`, `~optional`) are enumerable.
      * @default false

package/build/system/settings/settings.mjs

@@ -4,6 +4,7 @@ const settings = {
     immutableTypes: false,
     maxErrors: 8,
     useEval: true,
+    exactOptionalPropertyTypes: false,
     enumerableKind: false
 };
 /** Resets system settings to defaults */
@@ -11,6 +12,7 @@ export function Reset() {
     settings.immutableTypes = false;
     settings.maxErrors = 8;
     settings.useEval = true;
+    settings.exactOptionalPropertyTypes = false;
     settings.enumerableKind = false;
 }
 /** Sets system settings */

package/build/value/convert/from-object.d.mts

@@ -1,2 +1,2 @@
-import type { TObject, TProperties } from '../../type/index.mjs';
+import { type TObject, type TProperties } from '../../type/index.mjs';
 export declare function FromObject(context: TProperties, type: TObject, value: unknown): unknown;

package/build/value/convert/from-object.mjs

@@ -1,14 +1,32 @@
 // deno-fmt-ignore-file
+import { IsOptional } from '../../type/index.mjs';
 import { Guard } from '../../guard/index.mjs';
 import { FromType } from './from-type.mjs';
 import { FromAdditionalProperties } from './from-additional.mjs';
+// ------------------------------------------------------------------
+// IsOptionalUndefined
+//
+// Determines whether a property should be excluded from conversion
+// because it is both optional and has an undefined value. This case
+// cannot be safely converted, since it introduces ambiguity between
+// an omitted optional property and a property explicitly set to the
+// value undefined.
+// ------------------------------------------------------------------
+function IsOptionalUndefined(property, key, value) {
+    return IsOptional(property) && Guard.IsUndefined(value[key]);
+}
+// ------------------------------------------------------------------
+// FromProperties
+// ------------------------------------------------------------------
 function FromProperties(context, type, value) {
     const entries = Guard.EntriesRegExp(type.properties);
     const keys = Guard.Keys(value);
-    for (const [regexp, schema] of entries) {
+    for (const [regexp, property] of entries) {
         for (const key of keys) {
-            if (regexp.test(key)) {
-                value[key] = FromType(context, schema, value[key]);
+            // Only convert the property if the value key matches a schema key,
+            // and the property is not optional with an undefined value.
+            if (regexp.test(key) && !IsOptionalUndefined(property, key, value)) {
+                value[key] = FromType(context, property, value[key]);
             }
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typebox",
   "description": "A Runtime Type System for JavaScript",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "keywords": [
     "typescript",
     "jsonschema"