lib0 0.2.109 → 0.2.111

package/schema.js

@@ -0,0 +1,504 @@
+/**
+ * @experimental WIP
+ *
+ * Simple & efficient schemas for your data.
+ */
+
+import * as obj from './object.js'
+import * as arr from './array.js'
+import * as error from './error.js'
+import * as env from './environment.js'
+
+/**
+ * @typedef {string|number|bigint|boolean|null|undefined} LiteralType
+ */
+
+/**
+ * @typedef {{ [k:string|number|symbol]: any }} AnyObject
+ */
+
+/**
+ * @template T
+ * @typedef {T extends $Schema<infer X> ? X : T} TypeOfSchema
+ */
+
+/**
+ * @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
+ */
+
+/**
+ * @template T
+ * @typedef {T extends $Schema<infer S> ? $Schema<S> : never} CastToSchema
+ */
+
+/**
+ * @template {unknown[]} Arr
+ * @typedef {Arr extends [...unknown[], infer L] ? L : never} TupleLast
+ */
+
+/**
+ * @template {unknown[]} Arr
+ * @typedef {Arr extends [...infer Fs, unknown] ? Fs : never} TuplePop
+ */
+
+const schemaSymbol = Symbol('0schema')
+
+/**
+ * @template T
+ */
+export class $Schema {
+  get [schemaSymbol] () { return true }
+  /**
+   * Use `schema.validate(obj)` with a typed parameter that is already of typed to be an instance of
+   * Schema. Validate will check the structure of the parameter and return true iff the instance
+   * really is an instance of Schema.
+   *
+   * @param {T} o
+   * @return {boolean}
+   */
+  validate (o) {
+    return this.check(o)
+  }
+
+  /* c8 ignore start */
+  /**
+   * Similar to validate, but this method accepts untyped parameters.
+   *
+   * @param {any} _o
+   * @return {_o is T}
+   */
+  check (_o) {
+    error.methodUnimplemented()
+  }
+  /* c8 ignore stop */
+
+  /**
+   * @type {$Schema<T?>}
+   */
+  get nullable () {
+    return union(this, null_)
+  }
+
+  /**
+   * @type {$Schema<T|undefined>}
+   */
+  get optional () {
+    return union(this, undefined_)
+  }
+
+  /**
+   * Cast a variable to a specific type. Returns the casted value, or throws an exception otherwise.
+   * Use this if you know that the type is of a specific type and you just want to convince the type
+   * system.
+   *
+   * **Do not rely on these error messages!**
+   * Performs an assertion check only if not in a production environment.
+   *
+   * @param {any} o
+   * @return {o extends T ? T : never}
+   */
+  cast (o) {
+    assert(o, this)
+    return o
+  }
+
+  /**
+   * Ensures that a variable is a a specific type. Returns the value, or throws an exception if the assertion check failed.
+   * Use this if you know that the type is of a specific type and you just want to convince the type
+   * system.
+   *
+   * Can be useful when defining lambdas: `s.lambda(s.$number, s.$void).ensure((n) => n + 1)`
+   *
+   * **Do not rely on these error messages!**
+   * Performs an assertion check if not in a production environment.
+   *
+   * @param {T} o
+   * @return {o extends T ? T : never}
+   */
+  ensure (o) {
+    assert(o, this)
+    return o
+  }
+}
+
+/**
+ * @template {(new (...args:any[]) => any) | ((...args:any[]) => any)} C
+ * @extends {$Schema<C extends ((...args:any[]) => infer T) ? T : (C extends (new (...args:any[]) => any) ? InstanceType<C> : never)>}
+ */
+export class $ConstructedBy extends $Schema {
+  /**
+   * @param {C} c
+   */
+  constructor (c) {
+    super()
+    this.v = c
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is C extends ((...args:any[]) => infer T) ? T : (C extends (new (...args:any[]) => any) ? InstanceType<C> : never)} o
+   */
+  check (o) {
+    return o?.constructor === this.v
+  }
+}
+
+/**
+ * @template {(new (...args:any[]) => any) | ((...args:any[]) => any)} C
+ * @param {C} c
+ * @return {CastToSchema<$ConstructedBy<C>>}
+ */
+export const constructedBy = c => new $ConstructedBy(c)
+
+/**
+ * @template {LiteralType} T
+ * @extends {$Schema<T>}
+ */
+export class $Literal extends $Schema {
+  /**
+   * @param {Array<T>} literals
+   */
+  constructor (literals) {
+    super()
+    this.v = literals
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is T}
+   */
+  check (o) {
+    return this.v.some(a => a === o)
+  }
+}
+
+/**
+ * @template {LiteralType[]} T
+ * @param {T} literals
+ * @return {CastToSchema<$Literal<T[number]>>}
+ */
+export const literal = (...literals) => new $Literal(literals)
+
+/**
+ * @template {{[key:string|symbol|number]: $Schema<any>}} S
+ * @extends {$Schema<{ [Key in keyof S]: S[Key] extends $Schema<infer Type> ? Type : never }>}
+ */
+export class $Object extends $Schema {
+  /**
+   * @param {S} v
+   */
+  constructor (v) {
+    super()
+    this.v = v
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is { [K in keyof S]: S[K] extends $Schema<infer Type> ? Type : never }}
+   */
+  check (o) {
+    return o != null && obj.every(this.v, (vv, vk) => vv.check(o[vk]))
+  }
+}
+
+/**
+ * @template {{ [key:string|symbol|number]: $Schema<any> }} T
+ * @param {T} def
+ * @return {CastToSchema<$Object<T>>}
+ */
+export const object = def => new $Object(def)
+
+/**
+ * @template {$Schema<string|number|symbol>} Keys
+ * @template {$Schema<any>} Values
+ * @extends {$Schema<Record<Keys extends $Schema<infer K> ? K : never,Values extends $Schema<infer T> ? T : never>>}
+ */
+export class $Record extends $Schema {
+  /**
+   * @param {Keys} keys
+   * @param {Values} values
+   */
+  constructor (keys, values) {
+    super()
+    this.keys = keys
+    this.values = values
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is Record<Keys extends $Schema<infer K> ? K : never,Values extends $Schema<infer T> ? T : never>}
+   */
+  check (o) {
+    return o != null && obj.every(o, (vv, vk) => this.keys.check(vk) && this.values.check(vv))
+  }
+}
+
+/**
+ * @template {$Schema<string|number|symbol>} Keys
+ * @template {$Schema<any>} Values
+ * @param {Keys} keys
+ * @param {Values} values
+ * @return {CastToSchema<$Record<Keys,Values>>}
+ */
+export const record = (keys, values) => new $Record(keys, values)
+
+/**
+ * @template {$Schema<any>[]} S
+ * @extends {$Schema<{ [Key in keyof S]: S[Key] extends $Schema<infer Type> ? Type : never }>}
+ */
+export class $Tuple extends $Schema {
+  /**
+   * @param {S} v
+   */
+  constructor (v) {
+    super()
+    this.v = v
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is { [K in keyof S]: S[K] extends $Schema<infer Type> ? Type : never }}
+   */
+  check (o) {
+    return o != null && obj.every(this.v, (vv, vk) => /** @type {$Schema<any>} */ (vv).check(o[vk]))
+  }
+}
+
+/**
+ * @template {Array<$Schema<any>>} T
+ * @param {T} def
+ * @return {CastToSchema<$Tuple<T>>}
+ */
+export const tuple = (...def) => new $Tuple(def)
+
+/**
+ * @template {$Schema<any>} S
+ * @extends {$Schema<Array<S extends $Schema<infer T> ? T : never>>}
+ */
+export class $Array extends $Schema {
+  /**
+   * @param {Array<S>} v
+   */
+  constructor (v) {
+    super()
+    /**
+     * @type {$Schema<S extends $Schema<infer T> ? T : never>}
+     */
+    this.v = v.length === 1 ? v[0] : new $Union(v)
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is Array<S extends $Schema<infer T> ? T : never>} o
+   */
+  check (o) {
+    return arr.isArray(o) && arr.every(o, oi => this.v.check(oi))
+  }
+}
+
+/**
+ * @template {Array<$Schema<any>>} T
+ * @param {T} def
+ * @return {$Schema<Array<T extends Array<$Schema<infer S>> ? S : never>>}
+ */
+export const array = (...def) => new $Array(def)
+
+/**
+ * @template T
+ * @extends {$Schema<T>}
+ */
+export class $InstanceOf extends $Schema {
+  /**
+   * @param {new (...args:any) => T} constructor
+   */
+  constructor (constructor) {
+    super()
+    this.v = constructor
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is T}
+   */
+  check (o) {
+    return o instanceof this.v
+  }
+}
+
+/**
+ * @template T
+ * @param {new (...args:any) => T} c
+ * @return {$Schema<T>}
+ */
+export const instance = c => new $InstanceOf(c)
+
+/**
+ * @template {$Schema<any>[]} Args
+ * @typedef {(...args:ExtractTypesFromSchemaArray<TuplePop<Args>>)=>TypeOfSchema<TupleLast<Args>>} _LArgsToLambdaDef
+ */
+
+/**
+ * @template {Array<$Schema<any>>} Args
+ * @extends {$Schema<_LArgsToLambdaDef<Args>>}
+ */
+export class $Lambda extends $Schema {
+  /**
+   * @param {Args} args
+   */
+  constructor (args) {
+    super()
+    this.len = args.length - 1
+    this.args = tuple(...args.slice(-1))
+    this.res = args[this.len]
+  }
+
+  /**
+   * @param {any} f
+   * @return {f is _LArgsToLambdaDef<Args>}
+   */
+  check (f) {
+    return f.constructor === Function && f.length <= this.len
+  }
+}
+
+/**
+ * @template {$Schema<any>[]} Args
+ * @param {Args} args
+ * @return {$Schema<(...args:ExtractTypesFromSchemaArray<TuplePop<Args>>)=>TypeOfSchema<TupleLast<Args>>>}
+ */
+export const lambda = (...args) => new $Lambda(args.length > 0 ? args : [void_])
+
+/**
+ * @template {Array<$Schema<any>>} T
+ * @extends {$Schema<Intersect<ExtractTypesFromSchemaArray<T>>>}
+ */
+export class $Intersection extends $Schema {
+  /**
+   * @param {T} v
+   */
+  constructor (v) {
+    super()
+    /**
+     * @type {T}
+     */
+    this.v = v
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is Intersect<ExtractTypesFromSchemaArray<T>>}
+   */
+  check (o) {
+    // @ts-ignore
+    return arr.every(this.v, check => check.check(o))
+  }
+}
+
+/**
+ * @template {$Schema<any>[]} T
+ * @param {T} def
+ * @return {CastToSchema<$Intersection<T>>}
+ */
+export const intersect = (...def) => new $Intersection(def)
+
+/**
+ * @template S
+ * @extends {$Schema<S>}
+ */
+export class $Union extends $Schema {
+  /**
+   * @param {Array<$Schema<S>>} v
+   */
+  constructor (v) {
+    super()
+    this.v = v
+  }
+
+  /**
+   * @param {any} o
+   * @return {o is S}
+   */
+  check (o) {
+    return arr.some(this.v, (vv) => vv.check(o))
+  }
+
+  static schema = constructedBy($Union)
+}
+
+/**
+ * @template {Array<$Schema<any>>} T
+ * @param {T} def
+ * @return {CastToSchema<$Union<T extends Array<$Schema<infer S>> ? S : never>>}
+ */
+export const union = (...def) => $Union.schema.check(def[0]) ? new $Union([...def[0].v, ...def.slice(1)]) : new $Union(def)
+
+/**
+ * @type {$Schema<any>}
+ */
+export const any = intersect()
+
+/**
+ * @type {$Schema<bigint>}
+ */
+export const bigint = constructedBy(BigInt)
+
+/**
+ * @type {$Schema<Symbol>}
+ */
+export const symbol = constructedBy(Symbol)
+
+/**
+ * @type {$Schema<number>}
+ */
+export const number = constructedBy(Number)
+
+/**
+ * @type {$Schema<string>}
+ */
+export const string = constructedBy(String)
+
+/**
+ * @type {$Schema<undefined>}
+ */
+const undefined_ = literal(undefined)
+
+/**
+ * @type {$Schema<void>}
+ */
+const void_ = undefined_
+
+/**
+ * @type {$Schema<null>}
+ */
+const null_ = literal(null)
+
+export { null_ as null, void_ as void, undefined_ as undefined }
+
+/* c8 ignore start */
+/**
+ * Assert that a variable is of this specific type.
+ * The assertion check is only performed in non-production environments.
+ *
+ * @type {<T>(o:any,schema:$Schema<T>) => asserts o is T}
+ */
+export const assert = env.production
+  ? () => {}
+  : (o, schema) => {
+      if (!schema.check(o)) {
+        throw error.create(`Expected value to be of type ${schema.constructor.name}.`)
+      }
+    }
+/* c8 ignore end */

package/schema.test.d.ts

@@ -0,0 +1,3 @@
+export function testSchemas(_tc: t.TestCase): void;
+import * as t from './testing.js';
+//# sourceMappingURL=schema.test.d.ts.map

package/schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.test.d.ts","sourceRoot":"","sources":["schema.test.js"],"names":[],"mappings":"AAOO,iCAFI,EAAE,QAAQ,QA6NpB;mBAlOkB,cAAc"}

package/sort.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sort.test.d.ts","sourceRoot":"","sources":["sort.test.js"],"names":[],"mappings":"AAoEO,kCAFI,EAAE,QAAQ,QAqBpB;AAKM,mCAFI,EAAE,QAAQ,QAqBpB;AAKM,mCAFI,EAAE,QAAQ,QAqBpB;AAKM,yCAFI,EAAE,QAAQ,QAoBpB;AAKM,+CAFI,EAAE,QAAQ,QA4BpB;mBA5LkB,cAAc"}
+{"version":3,"file":"sort.test.d.ts","sourceRoot":"","sources":["sort.test.js"],"names":[],"mappings":"AAoEO,kCAFI,EAAE,QAAQ,QAoBpB;AAKM,mCAFI,EAAE,QAAQ,QAoBpB;AAKM,mCAFI,EAAE,QAAQ,QAoBpB;AAKM,yCAFI,EAAE,QAAQ,QAoBpB;AAKM,+CAFI,EAAE,QAAQ,QA4BpB;mBAzLkB,cAAc"}

package/test.html

@@ -154,6 +154,7 @@
   "lib0/performance.js": "./performance.js",
   "lib0/dist/performance.cjs": "./dist/performance.node.cjs",
   "lib0/performance": "./performance.js",
+  "lib0/schema": "./schema.js",
   "isomorphic.js": "./node_modules/isomorphic.js/browser.mjs",
   "isomorphic.js/package.json": "./node_modules/isomorphic.js/package.json"
 },

package/test.js

@@ -39,7 +39,7 @@ import * as list from './list.test.js'
 import * as cache from './cache.test.js'
 import * as symbol from './symbol.test.js'
 import * as traits from './traits.test.js'
-
+import * as schema from './schema.test.js'
 import { isBrowser, isNode } from './environment.js'
 
 /* c8 ignore next */
@@ -86,7 +86,8 @@ runTests({
   list,
   cache,
   symbol,
-  traits
+  traits,
+  schema
 }).then(success => {
   /* c8 ignore next */
   if (isNode) {

package/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["testing.js"],"names":[],"mappings":";AA+DA,gCAAiD;AAGjD,oCAAmG;AAEnG;IACE;;;OAGG;IACH,wBAHW,MAAM,YACN,MAAM,EAmBhB;IAhBC;;OAEG;IACH,YAFU,MAAM,CAEY;IAC5B;;OAEG;IACH,UAFU,MAAM,CAEQ;IACxB;;;;OAIG;IACH,MAFU,IAAI,MAAM,EAAC,GAAG,CAAC,CAEJ;IACrB,qBAAiB;IACjB,wBAAiB;IAGnB,kBAGC;IAED;;OAEG;IAEH,mBAOC;IAED;;;;OAIG;IACH,sBAMC;CACF;AAED,oCAA6E;AAgBtE,gCANI,MAAM,QACN,MAAM,YACG,QAAQ,KAAE,IAAI,GAAC,QAAQ,GAAG,CAAC,KACpC,MAAM,iBACN,MAAM,oBA0EhB;AAcM,sCAHI,MAAM,SACN,MAAM,QAEwF;AAYlG,2BAFI,MAAM,QAE6B;AAE9C,yDAAoC;AAEpC,8EAA0C;AAoBnC,mCAHI,MAAM,eACM,GAAG,OAAE,IAAI,QAS/B;AAoBM,wCAHI,MAAM,eACM,GAAG,OAAE,QAAQ,GAAG,CAAC,iBASvC;AAoBM,qCAJI,MAAM,eACM,GAAG,OAAE,IAAI,GACpB,MAAM,CAYjB;AAoBM,0CAJI,MAAM,eACM,GAAG,OAAE,QAAQ,GAAG,CAAC,GAC5B,QAAQ,MAAM,CAAC,CAY1B;AASM,4EAFK,OAAO,CAYlB;AAQM,kCALI,MAAM,KACN,MAAM,gCAUhB;AASM,mFAA2F;AA8H3F,oGAFa,GAAG,0BAAK,MAAM,QAAC,GAAG,KAAE,OAAO,wBAE8E;AAUtH,gHAA8H;AAK9H,6CAFgB,GAAG,OAAE,QAAQ,GAAG,CAAC,iBASvC;AAMM,mCAHgB,GAAG,OAAE,IAAI,QAW/B;AAMM,wCAHgB,GAAG,OAAE,QAAQ,GAAG,CAAC,iBAWvC;AAKM;QAFW,MAAM;YAAS,MAAM,UAAW,QAAQ,KAAE,IAAI,GAAC,QAAQ,GAAG,CAAC;;qBA2C5E;AAQM,6BAHI,MAAM,SAMhB;AAQM,4BAHI,OAAO,QAOjB;sBAhlBqB,WAAW"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["testing.js"],"names":[],"mappings":";AA8DA,gCAAiD;AAGjD,oCAAmG;AAEnG;IACE;;;OAGG;IACH,wBAHW,MAAM,YACN,MAAM,EAmBhB;IAhBC;;OAEG;IACH,YAFU,MAAM,CAEY;IAC5B;;OAEG;IACH,UAFU,MAAM,CAEQ;IACxB;;;;OAIG;IACH,MAFU,IAAI,MAAM,EAAC,GAAG,CAAC,CAEJ;IACrB,qBAAiB;IACjB,wBAAiB;IAGnB,kBAGC;IAED;;OAEG;IAEH,mBAOC;IAED;;;;OAIG;IACH,sBAMC;CACF;AAED,oCAA6E;AAgBtE,gCANI,MAAM,QACN,MAAM,YACG,QAAQ,KAAE,IAAI,GAAC,QAAQ,GAAG,CAAC,KACpC,MAAM,iBACN,MAAM,oBA0EhB;AAcM,sCAHI,MAAM,SACN,MAAM,QAEwF;AAYlG,2BAFI,MAAM,QAE6B;AAE9C,yDAAoC;AAEpC,8EAA0C;AAoBnC,mCAHI,MAAM,eACM,GAAG,OAAE,IAAI,QAS/B;AAoBM,wCAHI,MAAM,eACM,GAAG,OAAE,QAAQ,GAAG,CAAC,iBASvC;AAoBM,qCAJI,MAAM,eACM,GAAG,OAAE,IAAI,GACpB,MAAM,CAYjB;AAoBM,0CAJI,MAAM,eACM,GAAG,OAAE,QAAQ,GAAG,CAAC,GAC5B,QAAQ,MAAM,CAAC,CAY1B;AASM,4EAFK,OAAO,CAYlB;AAQM,kCALI,MAAM,KACN,MAAM,gCAUhB;AASM,mFAA2F;AA8H3F,oGAFa,GAAG,0BAAK,MAAM,QAAC,GAAG,KAAE,OAAO,wBAE8E;AAUtH,gHAA8H;AAK9H,6CAFgB,GAAG,OAAE,QAAQ,GAAG,CAAC,iBASvC;AAMM,mCAHgB,GAAG,OAAE,IAAI,QAW/B;AAMM,wCAHgB,GAAG,OAAE,QAAQ,GAAG,CAAC,iBAWvC;AAKM;QAFW,MAAM;YAAS,MAAM,UAAW,QAAQ,KAAE,IAAI,GAAC,QAAQ,GAAG,CAAC;;qBA2C5E;AAQM,6BAHI,MAAM,SAMhB;AAQM,4BAHI,OAAO,QAOjB;sBA/kBqB,WAAW"}

package/testing.js

@@ -60,7 +60,6 @@ import * as performance from 'lib0/performance'
 import * as traits from './traits.js'
 
 export { production } from './environment.js'
-
 export const extensive = env.hasConf('extensive')
 
 /* c8 ignore next */