feat: Add generic types and Complex numbers (#21)

Generic types can be called with argument(s) to produce a new type object, and if all types supplied as arguments are concrete, then the result will be a concrete type. The test of a generic type must determine if the entity is an instance of any specialization of the type; and it must also have a `refine` method that takes such an instance and returns its fully-specialized concrete type. It must also have a method `specializesTo` that takes a concrete type and returns whether that concrete type is a specialization of this generic type.

This commit also defines a generic Complex number type, that can have any type as its Component type (including another Complex number, to create e.g. quaternions), and defines the conversion/constructor function `complex`.

Reviewed-on: #21
Co-authored-by: Glen Whitney <glen@studioinfinity.org>
Co-committed-by: Glen Whitney <glen@studioinfinity.org>

src/complex/Complex.js

@@ -0,0 +1,75 @@
+import {Type} from '#core/Type.js'
+import {onType} from '#core/helpers.js'
+
+const isComplex = z => z && typeof z === 'object' && 're' in z && 'im' in z
+
+const specializesTo = CType => CType.complex
+
+function complexSpecialize(ComponentType) {
+   const compTest = ComponentType.test
+   const specTest = z => isComplex(z) && compTest(z.re) && compTest(z.im)
+   const typeName = `Complex(${ComponentType})`
+   if (ComponentType.concrete) {
+      const fromSpec = [
+         ComponentType, math => r => ({re: r, im: ComponentType.zero})]
+      for (const  [matchType, fctry] of ComponentType.from.patterns) {
+         fromSpec.push(this.specialize(matchType.type), math => {
+            const compConv = fctry(math)
+            return z => ({re: compConv(z.re), im: compConv(z.im)})
+         })
+      }
+      const typeOptions = {from: onType(...fromSpec), typeName}
+      if ('zero' in ComponentType) {
+         typeOptions.zero = {re: ComponentType.zero, im: ComponentType.zero}
+         if ('one' in ComponentType) {
+            typeOptions.one = {re: ComponentType.one, im: ComponentType.zero}
+         }
+      }
+      if ('nan' in ComponentType) {
+         typeOptions.nan = {re: ComponentType.nan, im: ComponentType.nan}
+      }
+      const complexCompType = new Type(specTest, typeOptions)
+      complexCompType.Component = ComponentType
+      complexCompType.complex = true
+      return complexCompType
+   }
+   // wrapping a generic type in Complex
+   const cplx = this
+
+   const innerSpecialize = (...args) => {
+      const innerType = ComponentType.specialize(...args)
+      return cplx.specialize(innerType)
+   }
+
+   const innerSpecializesTo = CType => specializesTo(CType)
+       && ComponentType.specializesTo(CType.Component)
+
+   const innerRefine = (z, typer) => {
+      const reType = ComponentType.refine(z.re, typer)
+      const imType = ComponentType.refine(z.im, typer)
+      if (reType === imType) return cplx.specialize(reType)
+      throw new TypeError(
+         'mixed-type Complex numbers disallowed '
+            + `(real: ${reType}, imaginary: ${imType})`)
+   }
+
+   return new Type(specTest, {
+      specialize: innerSpecialize,
+      specializesTo: innerSpecializesTo,
+      refine: innerRefine,
+      typeName,
+   })
+}
+
+export const Complex = new Type(isComplex, {
+   specialize: complexSpecialize,
+   specializesTo,
+   refine: function(z, typer) {
+      const reType = typer(z.re)
+      const imType = typer(z.im)
+      if (reType === imType) return this.specialize(reType)
+      throw new TypeError(
+         'mixed-type Complex numbers disallowed '
+         + `(real: ${reType}, imaginary: ${imType})`)
+   }
+})