various tweaks; simplify dom_glob; add arr

Author: mitranim

.eslintrc

@@ -17,6 +17,8 @@
     "TextDecoder": "readonly",
     "TextEncoder": "readonly",
     "ReadableStream": "readonly",
+    "performance": "readonly",
+    "crypto": "readonly",
   },
   "rules": {
     "no-restricted-globals": ["error",

arr.mjs

@@ -0,0 +1,127 @@
+import * as l from './lang.mjs'
+
+/*
+Subclass of `Array` with a better constructor signature, and with various method
+overrides that prevent surprising semantics and amortize performance penalties.
+
+See implementation notes in `arr_bench.mjs`.
+
+Not recommended for actual use. Subclasses of `Array` have bad performance and
+other issues. Prefer `Vec`.
+*/
+export class Arr extends Array {
+  constructor(src) {
+    if (l.isNum(src)) {
+      super(src)
+      return
+    }
+
+    src = l.toTrueArr(src)
+
+    const len = src.length
+    super(len)
+
+    let ind = -1
+    while (++ind < len) this[ind] = src[ind]
+  }
+
+  /* Overrides for standard behaviors. */
+
+  lastIndexOf(val) {
+    if (val !== val) return -1
+    let ind = this.length
+    while (--ind >= 0) if (this[ind] === val) return ind
+    return ind
+  }
+
+  slice(...val) {
+    const buf = this.toArray()
+    return val.length ? buf.concat(...val) : buf
+  }
+
+  concat(...val) {
+    const buf = this.toArray()
+    return val.length ? buf.concat(...val) : buf
+  }
+
+  join(val) {return this.toArray().join(val)}
+
+  reverse() {
+    const len = this.length
+    const max = (len / 2) | 0
+    let ind = -1
+
+    while (++ind < max) {
+      const mir = len - 1 - ind
+      const val = this[ind]
+
+      this[ind] = this[mir]
+      this[mir] = val
+    }
+    return this
+  }
+
+  flat(...val) {return this.toArray().flat(...val)}
+  every(...val) {return this.toArray().every(...val)}
+  filter(...val) {return this.toArray().filter(...val)}
+  find(...val) {return this.toArray().find(...val)}
+  findIndex(...val) {return this.toArray().findIndex(...val)}
+  findLast(...val) {return this.toArray().findLast(...val)}
+  findLastIndex(...val) {return this.toArray().findLastIndex(...val)}
+  flatMap(...val) {return this.toArray().flatMap(...val)}
+  forEach(...val) {return this.toArray().forEach(...val)}
+  map(...val) {return this.toArray().map(...val)}
+  reduce(...val) {return this.toArray().reduce(...val)}
+  reduceRight(...val) {return this.toArray().reduceRight(...val)}
+  some(...val) {return this.toArray().some(...val)}
+
+  sort(fun) {
+    const src = this.toArray().sort(fun)
+    const len = src.length
+    let ind = -1
+    while (++ind < len) this[ind] = src[ind]
+    return this
+  }
+
+  keys() {return this.toArray().keys()}
+  values() {return this.toArray().values()}
+  entries() {return this.toArray().entries()}
+  [Symbol.iterator]() {return this.values()}
+
+  static from(src, fun) {
+    src = l.toTrueArr(src)
+
+    const len = src.length
+    const buf = this.make(len)
+    let ind = -1
+
+    if (l.optFun(fun)) while (++ind < len) buf[ind] = fun(src[ind], ind)
+    else while (++ind < len) buf[ind] = src[ind]
+    return buf
+  }
+
+  static of(...src) {return this.from(src)}
+
+  /* Non-standard extensions. */
+
+  add(val) {return this.push(val), this}
+
+  setLen(val) {
+    val = l.reqNum(val)
+    if (this.length !== val) this.length = val
+    return this
+  }
+
+  clear() {return this.setLen(0)}
+
+  // Our amortizer and bottleneck. Our savior and destroyer.
+  toArray() {
+    const len = this.length
+    const buf = Array(len)
+    let ind = -1
+    while (++ind < len) buf[ind] = this[ind]
+    return buf
+  }
+
+  static make(len) {return new this(len)}
+}

coll.mjs

@@ -28,7 +28,8 @@ export class Bset extends Set {
 
 export class ClsSet extends Bset {
   get cls() {return Object}
-  add(val) {return super.add(l.toInst(val, this.cls))}
+  add(val) {return super.add(this.make(val))}
+  make(val) {return l.toInst(val, this.cls)}
 }
 
 export function bmap(val) {return new Bmap(val)}
@@ -79,7 +80,8 @@ export class Bmap extends Map {
 
 export class ClsMap extends Bmap {
   get cls() {return Object}
-  set(key, val) {super.set(key, l.toInst(val, this.cls))}
+  set(key, val) {super.set(key, this.make(val))}
+  make(val) {return l.toInst(val, this.cls)}
 }
 
 // Short for "primary key optional".
@@ -119,12 +121,13 @@ export class Coll extends Bmap {
 export class ClsColl extends Coll {
   get cls() {return Object}
   set(key, val) {return super.set(key, l.reqInst(val, this.cls))}
-  add(val) {return super.add(l.toInst(val, this.cls))}
-  addOpt(val) {return super.addOpt(l.toInst(val, this.cls))}
+  add(val) {return super.add(this.make(val))}
+  addOpt(val) {return super.addOpt(this.make(val))}
+  make(val) {return l.toInst(val, this.cls)}
 }
 
 export class Vec extends l.Emp {
-  constructor(val) {super().$ = l.laxArr(val)}
+  constructor(val) {super().$ = l.laxTrueArr(val)}
 
   add(val) {return this.$.push(val), this}
 
@@ -142,28 +145,17 @@ export class Vec extends l.Emp {
 
   [Symbol.iterator]() {return this.$.values()}
 
-  static of(...val) {return new this(Array.of(...val))}
-
-  static from(val) {
-    if (l.isNil(val)) return new this()
-    return new this(Array.from(l.reqIter(val)))
-  }
-
   static make(len) {return new this(Array(l.reqNat(len)))}
+  static from(val) {return new this(l.toTrueArr(val))}
+  static of(...val) {return new this(Array.of(...val))}
 }
 
 // Short for "class vector".
 export class ClsVec extends Vec {
-  constructor(val) {
-    super(val)
-    if (!this.$.every(selfIsInst, this)) {
-      this.$ = this.$.map(selfToInst, this)
-    }
-  }
-
-  add(val) {return super.add(l.toInst(val, this.cls))}
-
   get cls() {return Object}
+  constructor(src) {super().addFrom(src)}
+  add(val) {return super.add(this.make(val))}
+  make(val) {return l.toInst(val, this.cls)}
 }
 
 export class Que extends Set {
@@ -188,8 +180,3 @@ export class Que extends Set {
     return this
   }
 }
-
-/* Internal */
-
-function selfIsInst(val) {return l.isInst(val, this.cls)}
-function selfToInst(val) {return l.toInst(val, this.cls)}

doc/cmd_doc.mjs

@@ -39,7 +39,7 @@ const FEATS = [
   [`test`, `tools for testing and benchmarking.`],
 ]
 
-class Pkg extends o.MemGet {
+class Pkg extends o.Strict {
   constructor(feats) {
     super()
     this.feats = new co.Coll()
@@ -48,6 +48,7 @@ class Pkg extends o.MemGet {
     }
   }
 
+  static {o.memGet(this)}
   get base() {return `https://cdn.jsdelivr.net/npm/@mitranim/js`}
   get ver() {return VER}
   get url() {return s.inter(this.base, `@`, this.ver)}
@@ -73,7 +74,7 @@ class Pkg extends o.MemGet {
   featUrl(name) {return this.feat(name).selfUrl}
 }
 
-class Feat extends o.MemGet {
+class Feat extends o.Strict {
   constructor(pkg, name, desc) {
     super()
     this.pkg = l.reqInst(pkg, Pkg)
@@ -83,6 +84,7 @@ class Feat extends o.MemGet {
 
   pk() {return this.name}
 
+  static {o.memGet(this)}
   get codePath() {return s.str(this.name, `.mjs`)}
   get docCodePath() {return u.urlJoin(`..`, this.codePath)}
   get codeHead() {return mdLink(this.codePath, this.docCodePath)}
@@ -216,7 +218,7 @@ ${s.joinLines(i.map(idents, toUndocBullet))}
   featUrl(name) {return this.pkg.featUrl(name)}
 }
 
-class Ident extends o.MemGet {
+class Ident extends o.Strict {
   constructor(feat, line, type, name) {
     super()
     this.feat = l.reqInst(feat, Feat)
@@ -227,6 +229,7 @@ class Ident extends o.MemGet {
 
   pk() {return this.name}
 
+  static {o.memGet(this)}
   get row() {return this.line + 1}
   get testRow() {return this.$testRow()}
   get testLine() {return this.$testLine()}

doc/coll/_Vec.md

@@ -9,7 +9,7 @@ Short for "vector". Thin wrapper around a plain array. Features:
 Differences and advantages over `Array`:
 
   * Better constructor signature.
-    * Constructor takes exactly one argument, which is either {{link lang isNil nil}} or an {{link lang isArr array}}.
+    * Constructor takes exactly one argument, which is either {{link lang isNil nil}} or an {{link lang isTrueArr array}}.
     * For comparison, the `Array` constructor has special cases that make subclassing difficult.
   * Can be subclassed without trashing performance.
     * At the time of writing, subclasses of `Array` suffer horrible deoptimization in V8.

doc/dom_glob_native_readme.md

@@ -13,7 +13,6 @@
 ```js
 import * as dg from '{{featUrl dom_glob_native}}'
 
-console.log(dg.document)
 console.log(dg.glob)
 ```
 

doc/dom_glob_shim_readme.md

@@ -13,7 +13,6 @@
 ```js
 import * as dg from '{{featUrl dom_glob_shim}}'
 
-console.log(dg.document)
 console.log(dg.glob)
 ```
 

doc/iter/arr.md

@@ -1,10 +1,10 @@
-Converts an arbitrary {{link lang isSeq sequence}} to an array. Allows the following inputs:
+Converts an arbitrary {{link lang isSeq sequence}} to an array. Supports the following inputs:
 
   * {{link lang isNil Nil}}: return `[]`.
-  * {{link lang isArr Array}}: copy via `.slice()`.
+  * {{link lang isTrueArr Array}}: return as-is.
   * {{link lang isList List}}: convert via `Array.prototype.slice`.
   * {{link lang isSet Set}} or arbitrary {{link lang isIterator iterator}}: convert to array by iterating.
 
-The output is always a shallow copy. Mutation doesn't affect the source.
+Unlike {{link iter values}}, this function rejects other inputs such as non-nil primitives, dicts, maps, arbitrary iterables, ensuring that the input is always a sequence.
 
-Unlike {{link iter values}}, `arr` rejects other inputs such as non-nil primitives, dicts, maps, arbitrary iterables, ensuring that the input is always a sequence.
+The input may or may not be a copy. To ensure copying, use {{link iter arrCopy}}.

doc/iter/arrCopy.md

@@ -1 +1 @@
-Like {{link iter arr}}, converts an arbitrary sequence to an array. Unlike `arr,` always makes a copy. Mutating the output doesn't affect the original.
+Similar to {{link iter arr}}, but always makes a copy, even if the input is already a true array.

doc/iter/mapCls.md

@@ -0,0 +1,26 @@
+Signature: `(Iter<A>, {new(A): B}) => B[]`.
+
+Similar to {{link iter map}}, but instead of taking an arbitrary function, takes a class and calls it with `new` for each element.
+
+```js
+import * as i from '{{featUrl iter}}'
+import * as o from '{{featUrl obj}}'
+
+class Model extends o.Dict {pk() {return this.id}}
+class Person extends Model {}
+
+console.log(i.mapCls(
+  [
+    {id: 1, name: `Mira`},
+    {id: 2, name: `Kara`},
+  ],
+  Person,
+))
+
+/*
+[
+  Person { id: 1, name: "Mira" },
+  Person { id: 2, name: "Kara" },
+]
+*/
+```

doc/lang/isTrueArr.md

@@ -0,0 +1,3 @@
+Similar to [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) and {{link lang isArr}}, but returns true only for instances of the _exact_ `Array` class, false for instances of subclasses.
+
+At the time of writing, subclasses of `Array` suffer horrible performance penalties in V8, and possibly in other engines. Using them can also cause deoptimization of code that would otherwise run much faster. We sometimes prioritize or even enforce "true" arrays for consistent performance.

doc/lang/toTrueArr.md

@@ -0,0 +1,6 @@
+Idempotent conversion to a {{link lang isTrueArr true array}}. Allowed inputs:
+
+  * {{link lang isNil Nil}} → return `[]`.
+  * {{link lang isTrueArr True array}} → return as-is.
+  * {{link lang isIter Iterable}} → convert to `Array`.
+  * Otherwise → `TypeError` exception.

doc/obj/pickKeys.md

@@ -1,3 +1,3 @@
 Signature: `({[Key: A]}, keys) => {[Key: A]}`.
 
-Returns a version of the given dict, keeping only the given properties. Keys can be either a `Set` or an arbitrary {{link iter arr sequence}}. Each key must satisfy {{link lang isKey}}. Existence is not required: missing properties are silently ignored. Returns an empty dict if the input is {{link lang isNil nil}}.
+Returns a version of the given dict, keeping only the given properties. Keys can be either a `Set` or an arbitrary {{link iter values sequence}}. Each key must satisfy {{link lang isKey}}. Existence is not required: missing properties are silently ignored. Returns an empty dict if the input is {{link lang isNil nil}}.

doc/prax_readme.md

@@ -120,7 +120,7 @@ import * as p from '{{featUrl prax}}'
 import * as dg from '{{featUrl dom_glob_shim}}'
 import * as dg from '{{featUrl dom_glob_native}}'
 
-const ren = new p.Ren(dg.document).patchProto(dg.glob.Element)
+const ren = p.Ren.from(dg.glob)
 ```
 
 Rendering a complete document with doctype:
@@ -129,7 +129,7 @@ Rendering a complete document with doctype:
 import * as p from '{{featUrl prax}}'
 import * as dg from '{{featUrl dom_glob_shim}}'
 
-const ren = new p.Ren(dg.document).patchProto(dg.glob.Element)
+const ren = p.Ren.from(dg.glob)
 const {E} = ren
 const A = p.PropBui.main
 

doc/readme.md

@@ -43,7 +43,7 @@ Alternatives that suck:
 
 ## Usage
 
-Uses native JS modules, which can be imported by URL in browsers and Deno. The truly lazy can import all core modules at once:
+Uses native JS modules, which can be imported by URL in browsers and Deno. The truly lazy can import many core modules at once:
 
 ```js
 import * as a from '{{url}}/all.mjs'