lib0 1.0.0-rc.23 → 1.0.0-rc.26

package/dist/schema.d.ts

@@ -191,21 +191,15 @@ export const $$constructedBy: Schema<$ConstructedBy<(new (...args: any[]) => any
  */
 export class $Custom extends Schema<any> {
     /**
-     * @param {(o:any) => boolean} check
+     * @param {(o:any,err?:ValidationError) => boolean} check
      */
-    constructor(check: (o: any) => boolean);
+    constructor(check: (o: any, err?: ValidationError) => boolean);
     /**
-     * @type {(o:any) => boolean}
+     * @type {(o:any,err?:ValidationError) => boolean}
      */
-    shape: (o: any) => boolean;
-    /**
-     * @param {any} o
-     * @param {ValidationError} err
-     * @return {o is any}
-     */
-    check(o: any, err: ValidationError): o is any;
+    shape: (o: any, err?: ValidationError) => boolean;
 }
-export function $custom(check: (o: any) => boolean): Schema<any>;
+export function $custom(check: (o: any, err?: ValidationError) => boolean): Schema<any>;
 export const $$custom: Schema<$Custom>;
 /**
  * @template {Primitive} T
@@ -220,6 +214,7 @@ export class $Literal<T extends Primitive> extends Schema<T> {
 }
 export function $literal<T extends Primitive[]>(...literals: T): CastToSchema<$Literal<T[number]>>;
 export const $$literal: Schema<$Literal<Primitive>>;
+export function $$literalWith<T extends Primitive[]>(...literals: T): Schema<CastToSchema<$Literal<T[number]>>>;
 /**
  * @template {Array<string|Schema<string|number>>} T
  * @extends {Schema<CastStringTemplateArgsToTemplate<T>>}
@@ -295,6 +290,10 @@ export function $partial<S extends {
     [key: string | symbol | number]: any;
 }>(def: S): Schema<Partial<_ObjectDefToSchema<S>>>;
 /**
+ * Matches plain objects only - `{}`-literals and `Object.create(null)` objects, not class
+ * instances. The check is prototype-based, not `o.constructor === Object`, because a plain
+ * object may declare an own property named "constructor".
+ *
  * @type {Schema<{[key:string]: any}>}
  */
 export const $objectAny: Schema<{
@@ -480,6 +479,22 @@ export const $$symbol: Schema<Schema<Symbol>>;
  */
 export const $number: Schema<number>;
 export const $$number: Schema<Schema<number>>;
+/**
+ * A number without fractional component (`Number.isInteger`). The unwrapped type is still
+ * `number` - JS has no separate integer type.
+ *
+ * @type {Schema<number>}
+ */
+export const $int: Schema<number>;
+export const $$int: Schema<Schema<number>>;
+/**
+ * An unsigned integer: a number without fractional component that is `>= 0`. The unwrapped type is
+ * still `number` - JS has no separate integer type.
+ *
+ * @type {Schema<number>}
+ */
+export const $uint: Schema<number>;
+export const $$uint: Schema<Schema<number>>;
 /**
  * @type {Schema<string>}
  */
@@ -490,18 +505,26 @@ export const $$string: Schema<Schema<string>>;
  */
 export const $boolean: Schema<boolean>;
 export const $$boolean: Schema<Schema<boolean>>;
+/**
+ * `$true`, `$false`, `$undefined` & `$null` are plain `$Literal`s (no own `$type`), so the generic
+ * `$$literal` handling covers them in `random`, `coerce` & error messages.
+ *
+ * @type {Schema<true>}
+ */
+export const $true: Schema<true>;
+/**
+ * @type {Schema<false>}
+ */
+export const $false: Schema<false>;
 /**
  * @type {Schema<undefined>}
  */
 export const $undefined: Schema<undefined>;
-export const $$undefined: Schema<Schema<undefined>>;
 /**
  * @type {Schema<void>}
  */
 export const $void: Schema<void>;
-export const $$void: Schema<Schema<void>>;
 export const $null: Schema<null>;
-export const $$null: Schema<Schema<null>>;
 export const $uint8Array: Schema<Uint8Array<ArrayBuffer>>;
 export const $$uint8Array: Schema<Schema<Uint8Array>>;
 export const $promise: Schema<Promise<unknown>>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lib0",
-  "version": "1.0.0-rc.23",
-  "description": "",
+  "version": "1.0.0-rc.26",
+  "description": "isomorphic utility functions",
   "sideEffects": false,
   "type": "module",
   "funding": {
@@ -9,9 +9,9 @@
     "url": "https://github.com/sponsors/dmonad"
   },
   "bin": {
-    "0gentesthtml": "./src/bin/gentesthtml.js",
-    "0serve": "./src/bin/0serve.js",
-    "0ecdsa-generate-keypair": "./src/bin/0ecdsa-generate-keypair.js"
+    "0gentesthtml": "src/bin/gentesthtml.js",
+    "0serve": "src/bin/0serve.js",
+    "0ecdsa-generate-keypair": "src/bin/0ecdsa-generate-keypair.js"
   },
   "files": [
     "dist/**/*.d.ts",

package/src/delta/delta.js

@@ -822,6 +822,10 @@ export class ModifyOp extends list.ListNode {
    * @return {ModifyOp<DTypes>}
    */
   clone (_start = 0, _end = 1, markAsDone = true) {
+    // `markAsDone=false` is currently unreachable: only `_splitOp` passes `false`, and a length-1
+    // modify is never split (apply's `move ? op : op.clone(0, 1, keep)` evaluates the clone only when
+    // `keep` is true). Kept for the uniform children-op `clone` signature.
+    /* c8 ignore next */
     return new ModifyOp(/** @type {DTypes} */ (markAsDone ? this.value.done() : this.value), _cloneAttrs(this.format), _cloneAttrs(this.attribution))
   }
 }
@@ -2847,6 +2851,11 @@ const applyDim = (op, field, update) => {
     // additionally merges its nested `format` key one level (see {@link mergeAttr}); format stays shallow.
     const cur = /** @type {any} */ (op)[field]
     const merged = field === 'attribution' ? mergeAttr(cur, update, false) : object.assign({}, cur, update)
+    // the empty-merge guard is currently unreachable: a stored `update` is canonical (the builder's
+    // combine strips `{k:undefined}` keys and drops empty objects to `undefined`, which `applyDim`
+    // already returned on), and a verbatim (non-resolving) merge never removes keys — so `merged`
+    // keeps at least one key of `update`. Kept to document that an empty result means skip.
+    /* c8 ignore next */
     ;/** @type {any} */ (op)[field] = object.isEmpty(merged) ? undefined : merged
   } else if (field === 'attribution') {
     // data op, attribution: resolve per key; the nested `format` key merges one level (see {@link mergeAttr})
@@ -2857,6 +2866,9 @@ const applyDim = (op, field, update) => {
     let f = /** @type {any} */ (op)[field]
     for (const k in update) {
       const v = update[k]
+      // the skip is currently unreachable: a stored `update` never carries a `{k:undefined}` key
+      // (the builder's combine strips them). Kept for the unified tri-state contract.
+      /* c8 ignore next */
       if (v === undefined) continue // skip this key
       if (v === null) { // remove this key (no-op when the stored value is already `null`)
         if (f !== null) {
@@ -2915,6 +2927,9 @@ const diffDim = (aVal, bVal, deep) => {
  * @param {{[k:string]:any}|null|undefined} attributionUpdate
  */
 const updateOpFormat = (op, formatUpdate, attributionUpdate) => {
+  // defensive: apply's walk never passes a delete op (the initial `opsI` skips leading deletes and
+  // every advance goes through `opNextUndeleted`)
+  /* c8 ignore next */
   if ($deleteOp.check(op)) return
   const changedF = applyDim(op, 'format', formatUpdate)
   const changedA = applyDim(op, 'attribution', attributionUpdate)
@@ -2960,6 +2975,9 @@ const cmpKey = (a, b) =>
  * @param {Mark} a
  * @param {Mark} b
  */
+// the `: 0` id tie is unreachable: a Marks set is deduplicated by id (`add` replaces), so the sort
+// never compares two marks with the same id
+/* c8 ignore next */
 const cmpMarkKey = (a, b) => cmpKey(a.key, b.key) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
 
 /**

package/src/environment.common.js

@@ -31,7 +31,7 @@ export const globalScope = /* @__PURE__ */(() =>/** @type {any} */ (typeof globa
  * which has `btoa`/`atob`/`fetch` but no DOM). Excludes Node and Deno.
  * @type {boolean}
  */
-/* c8 ignore next */
+/* c8 ignore start */
 export const isBrowser = /* @__PURE__ */(() =>
   !isNode && !isDeno && (
     (typeof window !== 'undefined' && typeof document !== 'undefined') ||
@@ -39,3 +39,4 @@ export const isBrowser = /* @__PURE__ */(() =>
     (typeof globalScope.WorkerGlobalScope !== 'undefined' && globalScope.self instanceof globalScope.WorkerGlobalScope)
   )
 )()
+/* c8 ignore stop */

package/src/schema.js

@@ -5,6 +5,7 @@
  */
 
 import * as arr from './array.js'
+import * as buffer from './buffer.js'
 import * as error from './error.js'
 import * as equalityTraits from './trait/equality.js'
 import * as fun from './function.js'
@@ -356,23 +357,23 @@ export const $$constructedBy = $type('s:$ConstructedBy', $ConstructedBy)
  */
 export class $Custom extends Schema {
   /**
-   * @param {(o:any) => boolean} check
+   * @param {(o:any,err?:ValidationError) => boolean} check
    */
   constructor (check) {
     super()
     /**
-     * @type {(o:any) => boolean}
+     * @type {(o:any,err?:ValidationError) => boolean}
      */
     this.shape = check
   }
 
   /**
    * @param {any} o
-   * @param {ValidationError} err
+   * @param {ValidationError} [err]
    * @return {o is any}
    */
   check (o, err) {
-    const c = this.shape(o)
+    const c = this.shape(o, err)
     /* c8 ignore next */
     !c && err?.extend(null, 'custom prop', o?.constructor.name, 'failed to check custom prop')
     return c
@@ -380,7 +381,7 @@ export class $Custom extends Schema {
 }
 
 /**
- * @param {(o:any) => boolean} check
+ * @param {(o:any,err?:ValidationError) => boolean} check
  * @return {Schema<any>}
  */
 /* @__NO_SIDE_EFFECTS__ */
@@ -423,6 +424,17 @@ export class $Literal extends Schema {
 export const $literal = (...literals) => new $Literal(literals)
 export const $$literal = $type('s:$Literal', $Literal)
 
+/**
+ * Meta schema that matches a `$Literal` whose shape is exactly `literals` - e.g.
+ * `$$literalWith(null).check($null)` or `.if($$literalWith(true), ..)` in a pattern matcher.
+ *
+ * @template {Primitive[]} T
+ * @param {T} literals
+ * @return {Schema<CastToSchema<$Literal<T[number]>>>}
+ */
+/* @__NO_SIDE_EFFECTS__ */
+export const $$literalWith = (...literals) => $custom((o, err) => $$literal.check(o, err) && o.shape.length === literals.length && arr.every(o.shape, (l, i) => l === literals[i]))
+
 /**
  * @template {Array<string|Schema<string|number>>} Ts
  * @typedef {Ts extends [] ? `` : (Ts extends [infer T] ? (Unwrap<T> extends (string|number) ? Unwrap<T> : never) : (Ts extends [infer T1, ...infer Rest] ? `${Unwrap<T1> extends (string|number) ? Unwrap<T1> : never}${Rest extends Array<string|Schema<string|number>> ? CastStringTemplateArgsToTemplate<Rest> : never}` : never))} CastStringTemplateArgsToTemplate
@@ -623,9 +635,17 @@ export const $$object = /* @__PURE__ */$type('s:$Object', $Object)
 export const $partial = def => /** @type {any} */ (new $Object(def, true))
 
 /**
+ * Matches plain objects only - `{}`-literals and `Object.create(null)` objects, not class
+ * instances. The check is prototype-based, not `o.constructor === Object`, because a plain
+ * object may declare an own property named "constructor".
+ *
  * @type {Schema<{[key:string]: any}>}
  */
-export const $objectAny = $custom(o => o != null && (o.constructor === Object || o.constructor == null))
+export const $objectAny = $custom(o => {
+  if (o == null) return false
+  const proto = Object.getPrototypeOf(o)
+  return proto === Object.prototype || proto === null
+})
 
 /**
  * @template {Schema<string|number|symbol>} Keys
@@ -1007,6 +1027,24 @@ export const $$symbol = /** @type {Schema<Schema<Symbol>>} */ (/* @__PURE__ */$t
 export const $number = /* @__PURE__ */$custom(o => typeof o === 'number')
 export const $$number = /** @type {Schema<Schema<number>>} */ (/* @__PURE__ */$type('s:$number', $number))
 
+/**
+ * A number without fractional component (`Number.isInteger`). The unwrapped type is still
+ * `number` - JS has no separate integer type.
+ *
+ * @type {Schema<number>}
+ */
+export const $int = /* @__PURE__ */$custom(o => number.isInteger(o))
+export const $$int = /** @type {Schema<Schema<number>>} */ (/* @__PURE__ */$type('s:$int', $int))
+
+/**
+ * An unsigned integer: a number without fractional component that is `>= 0`. The unwrapped type is
+ * still `number` - JS has no separate integer type.
+ *
+ * @type {Schema<number>}
+ */
+export const $uint = /* @__PURE__ */$custom(o => number.isInteger(o) && o >= 0)
+export const $$uint = /** @type {Schema<Schema<number>>} */ (/* @__PURE__ */$type('s:$uint', $uint))
+
 /**
  * @type {Schema<string>}
  */
@@ -1019,20 +1057,30 @@ export const $$string = /** @type {Schema<Schema<string>>} */ (/* @__PURE__ */$t
 export const $boolean = /* @__PURE__ */$custom(o => typeof o === 'boolean')
 export const $$boolean = /** @type {Schema<Schema<Boolean>>} */ (/* @__PURE__ */$type('s:$boolean', $boolean))
 
+/**
+ * `$true`, `$false`, `$undefined` & `$null` are plain `$Literal`s (no own `$type`), so the generic
+ * `$$literal` handling covers them in `random`, `coerce` & error messages.
+ *
+ * @type {Schema<true>}
+ */
+export const $true = /* @__PURE__ */$literal(true)
+
+/**
+ * @type {Schema<false>}
+ */
+export const $false = /* @__PURE__ */$literal(false)
+
 /**
  * @type {Schema<undefined>}
  */
 export const $undefined = /* @__PURE__ */$literal(undefined)
-export const $$undefined = /** @type {Schema<Schema<undefined>>} */ (/* @__PURE__ */$type('s:$undefined', $undefined))
 
 /**
  * @type {Schema<void>}
  */
 export const $void = $undefined
-export const $$void = /** @type {Schema<Schema<void>>} */ ($$undefined)
 
 export const $null = $literal(null)
-export const $$null = /** @type {Schema<Schema<null>>} */ ($type('s:$null', $null))
 
 export const $uint8Array = $constructedBy(Uint8Array)
 export const $$uint8Array = /** @type {Schema<Schema<Uint8Array>>} */ ($type('s:$uint8Array', $uint8Array))
@@ -1165,9 +1213,10 @@ export const match = state => new PatternMatcher(/** @type {any} */ (state))
  */
 const _random = /* @__PURE__ */ (() => match({ gen: /** @type {Schema<prng.PRNG>} */ ($any), fallback: $lambda($any, $any, $any).optional })
   .if($$number, (_o, { gen }) => prng.oneOf(gen, [-1, 0, 1, prng.int53(gen, number.MIN_SAFE_INTEGER, number.MAX_SAFE_INTEGER)]))
+  .if($$int, (_o, { gen }) => prng.oneOf(gen, [-1, 0, 1, prng.int53(gen, number.MIN_SAFE_INTEGER, number.MAX_SAFE_INTEGER)]))
+  .if($$uint, (_o, { gen }) => prng.oneOf(gen, [0, 1, prng.int53(gen, 0, number.MAX_SAFE_INTEGER)]))
   .if($$string, (_o, { gen }) => prng.word(gen))
   .if($$boolean, (_o, { gen }) => prng.bool(gen))
-  .if($$undefined, (_o) => undefined)
   .if($$bigint, (_o, { gen }) => BigInt(prng.int53(gen, number.MIN_SAFE_INTEGER, number.MAX_SAFE_INTEGER)))
   .if($$union, (o, opts) => _random(prng.oneOf(opts.gen, o.shape), opts))
   .if($$object, (o, opts) => {
@@ -1199,9 +1248,6 @@ const _random = /* @__PURE__ */ (() => match({ gen: /** @type {Schema<prng.PRNG>
   .if($$literal, (o, { gen }) => {
     return prng.oneOf(gen, o.shape)
   })
-  .if($$null, (_o) => {
-    return null
-  })
   .if($$lambda, (o, opts) => {
     const res = _random(o.res, opts)
     return () => res
@@ -1259,6 +1305,8 @@ const _failed = Symbol('schema:coercion failed')
 
 const _bigintRegex = /^[+-]?\d+$/
 
+const _base64Regex = /^[A-Za-z0-9+/]+={0,2}$/
+
 /**
  * Render a value for an error message. Objects are only rendered by kind - printing them adds
  * noise (and `String` throws on null-prototype objects).
@@ -1322,10 +1370,12 @@ const _nameOf = $s => {
   if (_isMeta($$any, $s)) return 'any'
   if (_isMeta($$string, $s)) return 'string'
   if (_isMeta($$number, $s)) return 'number'
+  if (_isMeta($$int, $s)) return 'int'
+  if (_isMeta($$uint, $s)) return 'uint'
   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)) {
+  if (_isMeta($$literal, $s)) {
     return /** @type {Array<Primitive>} */ (shape).map(l => String(l)).join(' | ')
   }
   if (_isMeta($$optional, $s)) return `${_nameOf(shape)} | undefined`
@@ -1342,8 +1392,7 @@ const _nameOf = $s => {
 
 /**
  * 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`.
+ * an exact identity check.
  *
  * @param {Schema<any>} $s
  * @param {Map<Schema<any>,_Coercer>} cache
@@ -1373,6 +1422,18 @@ const _createCoercer = ($s, cache) => {
       return _fail(ctx, path, o, expected)
     }
   }
+  if (_isMeta($$int, $s) || _isMeta($$uint, $s)) {
+    const min = _isMeta($$uint, $s) ? 0 : -Infinity
+    return (o, path, ctx) => {
+      if (number.isInteger(o) && o >= min) return o
+      const t = typeof o
+      if (t === 'boolean' || t === 'bigint' || (t === 'string' && o.trim() !== '')) {
+        const n = Number(o)
+        if (number.isInteger(n) && n >= min) return n
+      }
+      return _fail(ctx, path, o, expected)
+    }
+  }
   if (_isMeta($$bigint, $s)) {
     return (o, path, ctx) => {
       const t = typeof o
@@ -1388,7 +1449,21 @@ const _createCoercer = ($s, cache) => {
       ? o
       : (o === 'true' ? true : (o === 'false' ? false : _fail(ctx, path, o, expected)))
   }
-  if (_isMeta($$literal, $s) || _isMeta($$null, $s) || _isMeta($$undefined, $s)) {
+  if (_isMeta($$uint8Array, $s)) {
+    // the format is checked here (rather than left to the decoder) because the `buffer.fromBase64`
+    // backends disagree on invalid input: `Buffer` silently ignores unexpected characters, `atob` &
+    // `Uint8Array.fromBase64` throw
+    return (o, path, ctx) => {
+      if ($uint8Array.check(o)) return o
+      if (typeof o !== 'string' || !_base64Regex.test(o)) return _fail(ctx, path, o, expected)
+      // base64 encodes 3 bytes as 4 characters. The '=' padding is optional, but when it is there
+      // the length has to be a multiple of 4 - and without it the last chunk must not be a single
+      // character, which carries no full byte.
+      const rest = o.length % 4
+      return (o.endsWith('=') ? rest === 0 : rest !== 1) ? buffer.fromBase64(o) : _fail(ctx, path, o, expected)
+    }
+  }
+  if (_isMeta($$literal, $s)) {
     const literals = /** @type {Array<Primitive>} */ (shape)
     return (o, path, ctx) => {
       if (arr.some(literals, l => l === o)) return o
@@ -1530,8 +1605,9 @@ const _buildCoercer = ($s, cache) => {
  * 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.
+ * `$tuple`, `$union`, `$optional`) are coerced recursively. `$uint8Array` accepts a base64 string
+ * (padding optional) - the inverse of `buffer.toBase64`. 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.