lib0 1.0.0-rc.21 → 1.0.0-rc.23

package/src/promise.js

@@ -14,13 +14,13 @@ import * as time from './time.js'
 
 /**
  * @template T
- * @param {function(PromiseResolve<T>,function(Error):void):any} f
+ * @param {(resolve: PromiseResolve<T>, reject: (err: Error) => void) => any} f
  * @return {Promise<T>}
  */
 export const create = f => /** @type {Promise<T>} */ (new Promise(f))
 
 /**
- * @param {function(function():void,function(Error):void):void} f
+ * @param {(resolve: () => void, reject: (err: Error) => void) => void} f
  * @return {Promise<void>}
  */
 export const createEmpty = f => new Promise(f)
@@ -59,7 +59,7 @@ export const resolveWith = res => Promise.resolve(res)
  * @deprecated use untilAsync instead
  *
  * @param {number} timeout
- * @param {function():boolean} check
+ * @param {() => boolean} check
  * @param {number} [intervalResolution]
  * @return {Promise<void>}
  */

package/src/schema.js

@@ -228,7 +228,7 @@ export class Schema {
    * Can be useful when defining lambdas: `s.lambda(s.$number, s.$number).expect((n) => n + 1)`
    *
    * @param {T} o
-   * @return {o extends T ? T : never}
+   * @return {T extends T ? T : never}
    */
   expect (o) {
     assert(o, this)
@@ -1058,8 +1058,8 @@ export const $primitive = $union($number, $string, $null, $undefined, $bigint, $
  * @type {Schema<null|number|string|boolean|JSON[]|{[key:string]:JSON}>}
  */
 export const $json = /* @__PURE__ */(() => {
-  const $jsonArr = /** @type {$Array<$any>} */ ($array($any))
-  const $jsonRecord = /** @type {$Record<$string,$any>} */ ($record($string, $any))
+  const $jsonArr = /** @type {$Array<typeof $any>} */ ($array($any))
+  const $jsonRecord = /** @type {$Record<typeof $string,typeof $any>} */ ($record($string, $any))
   const $json = $union($number, $string, $null, $boolean, $jsonArr, $jsonRecord)
   $jsonArr.shape = $json
   $jsonRecord.shape.values = $json
@@ -1241,3 +1241,316 @@ const _random = /* @__PURE__ */ (() => match({ gen: /** @type {Schema<prng.PRNG>
  */
 /* @__NO_SIDE_EFFECTS__ */
 export const random = (gen, schema, fallback) => /* @__PURE__ */_random($(schema), { gen, fallback })
+
+/**
+ * Carries the reason of a failed coercion out of the recursion.
+ *
+ * @typedef {{ err: string }} _CoerceCtx
+ */
+
+/**
+ * A compiled coercer. Returns the coerced value, or `_failed` after writing the reason to
+ * `ctx.err`.
+ *
+ * @typedef {(o:any, path:string, ctx:_CoerceCtx) => any} _Coercer
+ */
+
+const _failed = Symbol('schema:coercion failed')
+
+const _bigintRegex = /^[+-]?\d+$/
+
+/**
+ * Render a value for an error message. Objects are only rendered by kind - printing them adds
+ * noise (and `String` throws on null-prototype objects).
+ *
+ * @param {any} o
+ * @return {string}
+ */
+/* @__NO_SIDE_EFFECTS__ */
+const _show = o => typeof o === 'string'
+  ? JSON.stringify(o)
+  : (o !== null && object.isObject(o) ? (arr.isArray(o) ? 'array' : 'object') : String(o))
+
+/**
+ * @param {_CoerceCtx} ctx
+ * @param {string} path
+ * @param {any} o
+ * @param {string} expected
+ * @return {typeof _failed}
+ */
+const _fail = (ctx, path, o, expected) => {
+  ctx.err = `${path === '' ? '' : `[${path}] `}${_show(o)} doesn't match ${expected}`
+  return _failed
+}
+
+/**
+ * @param {string} path
+ * @param {string} key
+ */
+/* @__NO_SIDE_EFFECTS__ */
+const _prop = (path, key) => path === '' ? key : `${path}.${key}`
+
+/**
+ * @param {string} path
+ * @param {number} i
+ */
+/* @__NO_SIDE_EFFECTS__ */
+const _idx = (path, i) => path === '' ? `${i}` : `${path}[${i}]`
+
+/**
+ * `$$x.check` is a type predicate. Dispatching through this indirection keeps `$s` from being
+ * narrowed to `never` in the negative branches of the coercer dispatch.
+ *
+ * @param {Schema<any>} $meta
+ * @param {Schema<any>} $s
+ * @return {boolean}
+ */
+const _isMeta = ($meta, $s) => $meta.check($s)
+
+/**
+ * A short, human readable name for a schema - used in coercion error messages.
+ *
+ * Only `$union` & `$optional` are descended into (`$union` flattens nested unions, so this
+ * terminates). Container shapes are *not* descended into - that's what makes this safe on
+ * self-referential schemas like `$json`.
+ *
+ * @param {Schema<any>} $s
+ * @return {string}
+ */
+const _nameOf = $s => {
+  const shape = /** @type {any} */ ($s).shape
+  if (_isMeta($$any, $s)) return 'any'
+  if (_isMeta($$string, $s)) return 'string'
+  if (_isMeta($$number, $s)) return 'number'
+  if (_isMeta($$bigint, $s)) return 'bigint'
+  if (_isMeta($$boolean, $s)) return 'boolean'
+  if (_isMeta($$symbol, $s)) return 'symbol'
+  if (_isMeta($$literal, $s) || _isMeta($$null, $s) || _isMeta($$undefined, $s)) {
+    return /** @type {Array<Primitive>} */ (shape).map(l => String(l)).join(' | ')
+  }
+  if (_isMeta($$optional, $s)) return `${_nameOf(shape)} | undefined`
+  if (_isMeta($$union, $s)) return /** @type {Array<Schema<any>>} */ (shape).map(_nameOf).join(' | ')
+  if (_isMeta($$object, $s)) return 'object'
+  if (_isMeta($$record, $s)) return 'record'
+  if (_isMeta($$tuple, $s)) return 'tuple'
+  if (_isMeta($$array, $s)) return 'array'
+  // `instanceof` instead of the meta schemas: `$uint8Array` & `$promise` overwrite their inherited
+  // `$type` with a more specific one, so `_isMeta($$constructedBy, ..)` doesn't hold for them
+  if ($s instanceof $ConstructedBy || $s instanceof $InstanceOf) return shape.name
+  return $s.constructor.name
+}
+
+/**
+ * Compile a coercer for `$s`. Dispatches on the meta schemas (`$$string`, `$$object`, ..) which are
+ * an exact identity check. The order matters: `$string` & friends are `$Custom` instances and
+ * `$null` & `$undefined` are `$Literal` instances that are only distinguishable by their `$type`.
+ *
+ * @param {Schema<any>} $s
+ * @param {Map<Schema<any>,_Coercer>} cache
+ * @return {_Coercer}
+ */
+const _createCoercer = ($s, cache) => {
+  // `shape` is only defined on the subclasses - see the comment on `Schema`
+  const shape = /** @type {any} */ ($s).shape
+  const expected = _nameOf($s)
+  if (_isMeta($$any, $s)) {
+    return o => o
+  }
+  if (_isMeta($$string, $s)) {
+    return (o, path, ctx) => {
+      const t = typeof o
+      return t === 'string' ? o : (t === 'number' || t === 'bigint' || t === 'boolean' ? o + '' : _fail(ctx, path, o, expected))
+    }
+  }
+  if (_isMeta($$number, $s)) {
+    return (o, path, ctx) => {
+      const t = typeof o
+      if (t === 'number') return o
+      if (t === 'boolean' || t === 'bigint' || (t === 'string' && o.trim() !== '')) {
+        const n = Number(o)
+        if (!number.isNaN(n)) return n
+      }
+      return _fail(ctx, path, o, expected)
+    }
+  }
+  if (_isMeta($$bigint, $s)) {
+    return (o, path, ctx) => {
+      const t = typeof o
+      return t === 'bigint'
+        ? o
+        : ((t === 'number' && number.isInteger(o)) || (t === 'string' && _bigintRegex.test(o))
+            ? BigInt(o)
+            : _fail(ctx, path, o, expected))
+    }
+  }
+  if (_isMeta($$boolean, $s)) {
+    return (o, path, ctx) => typeof o === 'boolean'
+      ? o
+      : (o === 'true' ? true : (o === 'false' ? false : _fail(ctx, path, o, expected)))
+  }
+  if (_isMeta($$literal, $s) || _isMeta($$null, $s) || _isMeta($$undefined, $s)) {
+    const literals = /** @type {Array<Primitive>} */ (shape)
+    return (o, path, ctx) => {
+      if (arr.some(literals, l => l === o)) return o
+      if (typeof o === 'string') {
+        const i = literals.findIndex(l => String(l) === o)
+        if (i >= 0) return literals[i]
+      }
+      return _fail(ctx, path, o, expected)
+    }
+  }
+  if (_isMeta($$optional, $s)) {
+    const c = _buildCoercer(shape, cache)
+    return (o, path, ctx) => o === undefined ? undefined : c(o, path, ctx)
+  }
+  if (_isMeta($$union, $s)) {
+    const members = /** @type {Array<Schema<any>>} */ (shape)
+    const cs = members.map($m => _buildCoercer($m, cache))
+    return (o, path, ctx) => {
+      // a value that already matches one of the members is never converted
+      if (arr.some(members, $m => $m.check(o))) return o
+      for (let i = 0; i < cs.length; i++) {
+        const v = cs[i](o, path, ctx)
+        if (v !== _failed) return v
+      }
+      return _fail(ctx, path, o, expected)
+    }
+  }
+  if (_isMeta($$object, $s)) {
+    const isPartial = /** @type {any} */ ($s)._isPartial
+    /**
+     * @type {Array<{ key: string, skippable: boolean, c: _Coercer }>}
+     */
+    const props = []
+    for (const key in shape) {
+      props.push({ key, skippable: isPartial || $$optional.check(shape[key]), c: _buildCoercer(shape[key], cache) })
+    }
+    return (o, path, ctx) => {
+      if (o === null || !object.isObject(o)) return _fail(ctx, path, o, expected)
+      let changed = false
+      /**
+       * @type {any}
+       */
+      const res = {}
+      for (let i = 0; i < props.length; i++) {
+        const { key, skippable, c } = props[i]
+        if (skippable && !object.hasProperty(o, key)) continue
+        const v = c(o[key], _prop(path, key), ctx)
+        if (v === _failed) return _failed
+        changed = changed || v !== o[key]
+        res[key] = v
+      }
+      // unknown props are preserved - `$Object` accepts them as well
+      return changed ? object.assign({}, o, res) : o
+    }
+  }
+  if (_isMeta($$record, $s)) {
+    const ckey = _buildCoercer(shape.keys, cache)
+    const cval = _buildCoercer(shape.values, cache)
+    return (o, path, ctx) => {
+      if (o === null || !object.isObject(o)) return _fail(ctx, path, o, expected)
+      let changed = false
+      /**
+       * @type {any}
+       */
+      const res = {}
+      for (const key in o) {
+        const p = _prop(path, key)
+        // keys are coerced only to validate them - the property name stays a string either way
+        if (ckey(key, p, ctx) === _failed) return _failed
+        const v = cval(o[key], p, ctx)
+        if (v === _failed) return _failed
+        changed = changed || v !== o[key]
+        res[key] = v
+      }
+      return changed ? res : o
+    }
+  }
+  if (_isMeta($$tuple, $s)) {
+    const cs = /** @type {Array<Schema<any>>} */ (shape).map($m => _buildCoercer($m, cache))
+    return (o, path, ctx) => {
+      if (!arr.isArray(o)) return _fail(ctx, path, o, expected)
+      let changed = false
+      // `$Tuple` doesn't constrain the length - additional items are preserved
+      const res = o.slice()
+      for (let i = 0; i < cs.length; i++) {
+        const v = cs[i](o[i], _idx(path, i), ctx)
+        if (v === _failed) return _failed
+        changed = changed || v !== o[i]
+        res[i] = v
+      }
+      return changed ? res : o
+    }
+  }
+  if (_isMeta($$array, $s)) {
+    const c = _buildCoercer(shape, cache)
+    return (o, path, ctx) => {
+      if (!arr.isArray(o)) return _fail(ctx, path, o, expected)
+      let changed = false
+      const res = new Array(o.length)
+      for (let i = 0; i < o.length; i++) {
+        const v = c(o[i], _idx(path, i), ctx)
+        if (v === _failed) return _failed
+        changed = changed || v !== o[i]
+        res[i] = v
+      }
+      return changed ? res : o
+    }
+  }
+  // everything else ($instanceOf, $constructedBy, $custom, $lambda, $intersect, $stringTemplate,
+  // $type, ..) has no meaningful conversion - accept the value iff it already matches
+  return (o, path, ctx) => $s.check(o) ? o : _fail(ctx, path, o, expected)
+}
+
+/**
+ * Compile with memoization. The coercer is registered *before* recursing so that self-referential
+ * schemas (e.g. `$json`) terminate.
+ *
+ * @param {Schema<any>} $s
+ * @param {Map<Schema<any>,_Coercer>} cache
+ * @return {_Coercer}
+ */
+const _buildCoercer = ($s, cache) => {
+  const cached = cache.get($s)
+  if (cached != null) return cached
+  // `self` is a box because the registered forwarder must close over a coercer that doesn't exist
+  // yet
+  /**
+   * @type {Array<_Coercer>}
+   */
+  const self = []
+  cache.set($s, (o, path, ctx) => self[0](o, path, ctx))
+  self.push(_createCoercer($s, cache))
+  return self[0]
+}
+
+/**
+ * Compile a coercion function for `schema`.
+ *
+ * Unlike `check` (which only validates) a coercion converts values that don't match yet - `'42'`
+ * becomes `42` for `$number`, `'true'` becomes `true` for `$boolean`. Values that already match
+ * are returned untouched (including object identity). Containers (`$object`, `$array`, `$record`,
+ * `$tuple`, `$union`, `$optional`) are coerced recursively. Schemas without a meaningful
+ * conversion (`$instanceOf`, `$custom`, ..) simply have to match.
+ *
+ * Failures are returned instead of thrown - this is the only api in lib0 that reports errors as a
+ * value.
+ *
+ * @example
+ *   const readConfig = coerce($object({ port: $number, dev: $boolean }))
+ *   readConfig({ port: '8080', dev: 'true' }) // => { err: null, result: { port: 8080, dev: true } }
+ *   readConfig({ port: 'x', dev: 'true' })    // => { err: '[port] "x" doesn\'t match number', result: null }
+ *
+ * @template {Schema<any>} S
+ * @param {S} schema
+ * @return {(o:any) => { err: string, result: null } | { err: null, result: Unwrap<S> }}
+ */
+/* @__NO_SIDE_EFFECTS__ */
+export const coerce = schema => {
+  const c = _buildCoercer(schema, new Map())
+  return o => {
+    const ctx = { err: '' }
+    const res = c(o, '', ctx)
+    return res === _failed ? { err: ctx.err, result: null } : { err: null, result: res }
+  }
+}

package/src/sort.js

@@ -14,7 +14,7 @@ import * as math from './math.js'
  * @param {Array<T>} arr
  * @param {number} lo
  * @param {number} hi
- * @param {function(T,T):number} compare
+ * @param {(a: T, b: T) => number} compare
  */
 export const _insertionSort = (arr, lo, hi, compare) => {
   for (let i = lo + 1; i <= hi; i++) {
@@ -29,7 +29,7 @@ export const _insertionSort = (arr, lo, hi, compare) => {
 /**
  * @template T
  * @param {Array<T>} arr
- * @param {function(T,T):number} compare
+ * @param {(a: T, b: T) => number} compare
  * @return {void}
  */
 export const insertionSort = (arr, compare) => {
@@ -41,7 +41,7 @@ export const insertionSort = (arr, compare) => {
  * @param {Array<T>} arr
  * @param {number} lo
  * @param {number} hi
- * @param {function(T,T):number} compare
+ * @param {(a: T, b: T) => number} compare
  */
 const _quickSort = (arr, lo, hi, compare) => {
   if (hi - lo < 42) {
@@ -80,7 +80,7 @@ const _quickSort = (arr, lo, hi, compare) => {
  *
  * @template T
  * @param {Array<T>} arr
- * @param {function(T,T):number} compare
+ * @param {(a: T, b: T) => number} compare
  * @return {void}
  */
 export const quicksort = (arr, compare) => {

package/src/storage.js

@@ -8,6 +8,8 @@
  * @module storage
  */
 
+import { isBrowser } from './environment.common.js'
+
 /* c8 ignore start */
 class VarStoragePolyfill {
   constructor () {
@@ -39,8 +41,10 @@ let usePolyfill = true
 
 /* c8 ignore start */
 try {
-  // if the same-origin rule is violated, accessing localStorage might thrown an error
-  if (typeof localStorage !== 'undefined' && localStorage) {
+  // Only use localStorage in the browser — node & deno also define a localStorage global, but
+  // with different semantics (in node it is non-functional unless `--localstorage-file` is set).
+  // If the same-origin rule is violated, accessing localStorage might throw an error.
+  if (isBrowser && typeof localStorage !== 'undefined' && localStorage) {
     _localStorage = localStorage
     usePolyfill = false
   }
@@ -56,7 +60,7 @@ export const varStorage = _localStorage
 /**
  * A polyfill for `addEventListener('storage', event => {..})` that does nothing if the polyfill is being used.
  *
- * @param {function({ key: string, newValue: string, oldValue: string }): void} eventHandler
+ * @param {(e: { key: string, newValue: string, oldValue: string }) => void} eventHandler
  * @function
  */
 /* c8 ignore next */
@@ -65,7 +69,7 @@ export const onChange = eventHandler => usePolyfill || addEventListener('storage
 /**
  * A polyfill for `removeEventListener('storage', event => {..})` that does nothing if the polyfill is being used.
  *
- * @param {function({ key: string, newValue: string, oldValue: string }): void} eventHandler
+ * @param {(e: { key: string, newValue: string, oldValue: string }) => void} eventHandler
  * @function
  */
 /* c8 ignore next */

package/src/testing.js

@@ -133,7 +133,7 @@ const repeatTestRegex = /^(repeat|repeating)\s/
 /**
  * @param {string} moduleName
  * @param {string} name
- * @param {function(TestCase):void|Promise<any>} f
+ * @param {(tc: TestCase) => void|Promise<any>} f
  * @param {number} i
  * @param {number} numberOfTests
  */
@@ -257,7 +257,7 @@ export const printCanvas = log.printCanvas
  * ```
  *
  * @param {string} description
- * @param {function(...any):void} f
+ * @param {(...args: Array<any>) => void} f
  */
 export const group = (description, f) => {
   log.group(log.BLUE, description)
@@ -284,7 +284,7 @@ export const group = (description, f) => {
  * ```
  *
  * @param {string} description
- * @param {function(...any):Promise<any>} f
+ * @param {(...args: Array<any>) => Promise<any>} f
  */
 export const groupAsync = async (description, f) => {
   log.group(log.BLUE, description)
@@ -310,7 +310,7 @@ export const groupAsync = async (description, f) => {
  * ```
  *
  * @param {string} message
- * @param {function(...any):void} f
+ * @param {(...args: Array<any>) => void} f
  * @return {number} Returns a promise that resolves the measured duration to apply f
  */
 export const measureTime = (message, f) => {
@@ -340,7 +340,7 @@ export const measureTime = (message, f) => {
  * ```
  *
  * @param {string} message
- * @param {function(...any):Promise<any>} f
+ * @param {(...args: Array<any>) => Promise<any>} f
  * @return {Promise<number>} Returns a promise that resolves the measured duration to apply f
  */
 export const measureTimeAsync = async (message, f) => {
@@ -428,7 +428,7 @@ const _failMessage = (message, reason, path) => fail(
  * @param {any} b
  * @param {string} path
  * @param {string?} message
- * @param {function(any,any,any,string,any):boolean} customCompare
+ * @param {(constructor: any, a: any, b: any, path: string, compareValues: any) => boolean} customCompare
  */
 const _compare = (a, b, path, message, customCompare) => {
   // we don't use assert here because we want to test all branches (istanbul errors if one branch is not tested)
@@ -519,22 +519,22 @@ const _compare = (a, b, path, message, customCompare) => {
  * @param {T} a
  * @param {T} b
  * @param {string?} [message]
- * @param {function(any,T,T,string,any):boolean} [customCompare]
+ * @param {(constructor: any, a: T, b: T, path: string, compareValues: any) => boolean} [customCompare]
  */
 export const compare = (a, b, message = null, customCompare = compareValues) => _compare(a, b, 'obj', message, customCompare)
 
 /**
- * @template T
- * @param {T} property
- * @param {string?} [message]
- * @return {asserts property is NonNullable<T>}
+ * `@type` (not `@param`/`@return`) is required — an assertion signature only narrows if the
+ * callee is declared with an explicit type annotation.
+ *
  * @throws {TestError}
+ * @type {<T>(property: T, message?: string|null) => asserts property is NonNullable<T>}
  */
 /* c8 ignore next */
 export const assert = (property, message = null) => { property || fail(`Assertion failed${message !== null ? `: ${message}` : ''}`) }
 
 /**
- * @param {function(...any):Promise<any>} f
+ * @param {(...args: Array<any>) => Promise<any>} f
  */
 export const promiseRejected = async f => {
   try {
@@ -546,7 +546,7 @@ export const promiseRejected = async f => {
 }
 
 /**
- * @param {function(...any):void} f
+ * @param {(...args: Array<any>) => void} f
  * @throws {TestError}
  */
 export const fails = f => {
@@ -560,7 +560,7 @@ export const fails = f => {
 }
 
 /**
- * @param {function(...any):Promise<any>} f
+ * @param {(...args: Array<any>) => Promise<any>} f
  * @throws {TestError}
  */
 export const failsAsync = async f => {
@@ -574,7 +574,7 @@ export const failsAsync = async f => {
 }
 
 /**
- * @param {Object<string, Object<string, function(TestCase):any|Promise<any>>>} tests
+ * @param {Object<string, Object<string, (tc: TestCase) => any|Promise<any>>>} tests
  */
 export const runTests = async tests => {
   /**