[lib0/schema] support optionals in object

Author: dmonad

component.js

@@ -101,6 +101,7 @@ const parseAttrVal = (val, type) => {
 }
 
 /**
+ * @template S
  * @typedef {Object} CONF
  * @property {string?} [CONF.template] Template for the shadow dom.
  * @property {string} [CONF.style] shadow dom style. Is only used when
@@ -118,7 +119,6 @@ const parseAttrVal = (val, type) => {
  * to event listener.
  * @property {function(S, S, Lib0Component<S>):Object<string,string>} [CONF.slots] Fill slots
  * automatically when state changes. Maps from slot-name to slot-html.
- * @template S
  */
 
 /**

diff.js

@@ -18,14 +18,12 @@ import { equalityStrict } from './function.js'
  * a === b // values match
  * ```
  *
+ * @template {string} T
  * @typedef {Object} SimpleDiff
  * @property {Number} index The index where changes were applied
  * @property {Number} remove The number of characters to delete starting
  *                                  at `index`.
  * @property {T} insert The new text to insert at `index` after applying
- *                           `delete`
- *
- * @template T
  */
 
 const highSurrogateRegex = /[\uD800-\uDBFF]/

package-lock.json

@@ -505,13 +505,13 @@
     "isomorphic.js": "^0.2.4"
   },
   "devDependencies": {
-    "@types/node": "^18.14.0",
+    "@types/node": "^24.0.14",
     "c8": "^10.1.3",
     "jsdoc-api": "^8.0.0",
     "jsdoc-plugin-typescript": "^2.2.1",
     "rollup": "^2.42.1",
     "standard": "^17.1.0",
-    "typescript": "^5.0.2"
+    "typescript": "^5.8.3"
   },
   "scripts": {
     "clean": "rm -rf dist *.d.ts */*.d.ts *.d.ts.map */*.d.ts.map",

package.json

@@ -19,24 +19,12 @@ import * as env from './environment.js'
 
 /**
  * @template T
- * @typedef {T extends $Schema<infer X> ? X : T} TypeOfSchema
+ * @typedef {T extends $Schema<infer X> ? X : T} Unwrap
  */
 
 /**
  * @template {readonly unknown[]} T
- * @typedef {T extends []
- *   ? {}
- *   : T extends [infer First]
- *   ? First
- *   : T extends [infer First, ...infer Rest]
- *   ? First & Intersect<Rest>
- *   : never
- * } Intersect
- */
-
-/**
- * @template {readonly unknown[]} T
- * @typedef {T extends readonly [$Schema<infer First>, ...infer Rest] ? [First, ...ExtractTypesFromSchemaArray<Rest>] : [] } ExtractTypesFromSchemaArray
+ * @typedef {T extends readonly [$Schema<infer First>, ...infer Rest] ? [First, ...UnwrapArray<Rest>] : [] } UnwrapArray
  */
 
 /**
@@ -54,6 +42,18 @@ import * as env from './environment.js'
  * @typedef {Arr extends [...infer Fs, unknown] ? Fs : never} TuplePop
  */
 
+/**
+ * @template {readonly unknown[]} T
+ * @typedef {T extends []
+ *   ? {}
+ *   : T extends [infer First]
+ *   ? First
+ *   : T extends [infer First, ...infer Rest]
+ *   ? First & Intersect<Rest>
+ *   : never
+ * } Intersect
+ */
+
 const schemaSymbol = Symbol('0schema')
 
 /**
@@ -93,10 +93,10 @@ export class $Schema {
   }
 
   /**
-   * @type {$Schema<T|undefined>}
+   * @type {$Optional<$Schema<T>>}
    */
   get optional () {
-    return union(this, undefined_)
+    return new $Optional(/** @type {$Schema<T>} */ (this))
   }
 
   /**
@@ -192,9 +192,38 @@ export class $Literal extends $Schema {
  */
 export const literal = (...literals) => new $Literal(literals)
 
+const isOptionalSymbol = Symbol('optional')
+/**
+ * @template {$Schema<any>} S
+ * @extends $Schema<Unwrap<S>|undefined>
+ */
+class $Optional extends $Schema {
+  /**
+   * @param {S} s
+   */
+  constructor (s) {
+    super()
+    this.s = s
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is (Unwrap<S>|undefined)}
+   */
+  check (o) {
+    return o === undefined || this.s.check(o)
+  }
+  get [isOptionalSymbol] () { return true }
+}
+
+/**
+ * @template {{ [key: string|symbol|number]: $Schema<any> }} S
+ * @typedef {{ [Key in keyof S as S[Key] extends $Optional<$Schema<any>> ? Key : never]?: S[Key] extends $Optional<$Schema<infer Type>> ? Type : never } & { [Key in keyof S as S[Key] extends $Optional<$Schema<any>> ? never : Key]: S[Key] extends $Schema<infer Type> ? Type : never }} $ObjectToType
+ */
+
 /**
  * @template {{[key:string|symbol|number]: $Schema<any>}} S
- * @extends {$Schema<{ [Key in keyof S]: S[Key] extends $Schema<infer Type> ? Type : never }>}
+ * @extends {$Schema<$ObjectToType<S>>}
  */
 export class $Object extends $Schema {
   /**
@@ -207,19 +236,21 @@ export class $Object extends $Schema {
 
   /**
    * @param {any} o
-   * @return {o is { [K in keyof S]: S[K] extends $Schema<infer Type> ? Type : never }}
+   * @return {o is $ObjectToType<S>}
    */
   check (o) {
     return o != null && obj.every(this.v, (vv, vk) => vv.check(o[vk]))
   }
 }
 
+// I used an explicit type annotation instead of $ObjectToType, so that the user doesn't see the
+// weird type definitions when inspecting type definions.
 /**
- * @template {{ [key:string|symbol|number]: $Schema<any> }} T
- * @param {T} def
- * @return {CastToSchema<$Object<T>>}
+ * @template {{ [key:string|symbol|number]: $Schema<any> }} S
+ * @param {S} def
+ * @return {$Schema<{ [Key in keyof S as S[Key] extends $Optional<$Schema<any>> ? Key : never]?: S[Key] extends $Optional<$Schema<infer Type>> ? Type : never } & { [Key in keyof S as S[Key] extends $Optional<$Schema<any>> ? never : Key]: S[Key] extends $Schema<infer Type> ? Type : never }>}
  */
-export const object = def => new $Object(def)
+export const object = def => /** @type {any} */ (new $Object(def))
 
 /**
  * @template {$Schema<string|number|symbol>} Keys
@@ -347,7 +378,7 @@ export const instance = c => new $InstanceOf(c)
 
 /**
  * @template {$Schema<any>[]} Args
- * @typedef {(...args:ExtractTypesFromSchemaArray<TuplePop<Args>>)=>TypeOfSchema<TupleLast<Args>>} _LArgsToLambdaDef
+ * @typedef {(...args:UnwrapArray<TuplePop<Args>>)=>Unwrap<TupleLast<Args>>} _LArgsToLambdaDef
  */
 
 /**
@@ -377,13 +408,13 @@ export class $Lambda extends $Schema {
 /**
  * @template {$Schema<any>[]} Args
  * @param {Args} args
- * @return {$Schema<(...args:ExtractTypesFromSchemaArray<TuplePop<Args>>)=>TypeOfSchema<TupleLast<Args>>>}
+ * @return {$Schema<(...args:UnwrapArray<TuplePop<Args>>)=>Unwrap<TupleLast<Args>>>}
  */
 export const lambda = (...args) => new $Lambda(args.length > 0 ? args : [void_])
 
 /**
  * @template {Array<$Schema<any>>} T
- * @extends {$Schema<Intersect<ExtractTypesFromSchemaArray<T>>>}
+ * @extends {$Schema<Intersect<UnwrapArray<T>>>}
  */
 export class $Intersection extends $Schema {
   /**
@@ -399,7 +430,7 @@ export class $Intersection extends $Schema {
 
   /**
    * @param {any} o
-   * @return {o is Intersect<ExtractTypesFromSchemaArray<T>>}
+   * @return {o is Intersect<UnwrapArray<T>>}
    */
   check (o) {
     // @ts-ignore

schema.js

@@ -225,3 +225,23 @@ export const testSchemas = _tc => {
     t.assert(!$fun3.validate(/** @type {(a: number, b: number) => undefined} */ (a, b) => undefined)) // too many parameters
   })
 }
+
+/**
+ * @param {t.TestCase} _tc
+ */
+export const testObjectSchemaOptionals = _tc => {
+  const schema = s.object({ a: s.number.optional, b: s.string.optional })
+  t.assert(schema.validate({ })) // should work
+  // @ts-expect-error
+  t.assert(!schema.validate({ a: 'str' })) // should throw a type error
+  const def = s.union(s.string,s.array(s.number))
+  const defOptional = def.optional
+  const defObject = s.object({ j: defOptional, k: def })
+  // @ts-expect-error
+  t.assert(!defObject.validate({ k: undefined }))
+  t.assert(defObject.validate({ k: [42]}))
+  // @ts-expect-error
+  t.assert(!defObject.validate({ k: [42], j: 42}))
+  t.assert(defObject.validate({ k: [42], j: 'str'}))
+  t.assert(defObject.validate({ k: [42], j: undefined}))
+}

schema.test.js

@@ -16,10 +16,9 @@ export const toArray = set => Array.from(set)
 /**
  * @template T
  * @param {Set<T>} set
- * @return {T}
+ * @return {T|undefined}
  */
-export const first = set =>
-  set.values().next().value ?? undefined
+export const first = set => set.values().next().value
 
 /**
  * @template T

set.js

@@ -31,7 +31,7 @@
  *  * runTests automatically tests all exported functions that start with "test".
  *  * The name of the function should be in camelCase and is used for the logging output.
  *  *
- *  * @param {t.TestCase} tc
+ *  * @ param {t.TestCase} tc
  *  *\/
  * export const testMyFirstTest = tc => {
  *   t.compare({ a: 4 }, { a: 4 }, 'objects are equal')

testing.js

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2022",
     "lib": ["ES2022", "dom"],
-    "module": "ES2022",
+    "module": "NodeNext",
     "allowJs": true,
     "checkJs": true,
     "declaration": true,