feat: Return type annotations (#53)

Provides the infrastructure to allow annotating the return types of functions, and does so for essentially every operation in the system (the only known exceptions being add, multiply, etc., on arbitrarily many arguments).

One main infrastructure enhancements are bounded template types, e.g. `T:number` being a template parameter where T can take on the type `number` or any subtype thereof.

A main internal enhancement is that base template types are no longer added to the typed universe; rather, there is a secondary, "meta" typed universe where they live. The primary point/purpose of this change is then the necessary search order for implementations can be much better modeled by typed-function's search order, using the `onMismatch` facility to redirect the search from fully instantiated implementations to the generic catchall implementations for each template (these catchalls live in the meta universe).

Numerous other small improvements and bugfixes were encountered along the way.

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

test/_pocomath.mjs

@@ -20,9 +20,56 @@ describe('The default full pocomath instance "math"', () => {
       assert.strictEqual(math.typeOf({re: 6.28, im: 2.72}), 'Complex<number>')
    })
 
+   it('can determine the return types of operations', () => {
+      assert.strictEqual(math.returnTypeOf('negate', 'number'), 'number')
+      assert.strictEqual(math.returnTypeOf('negate', 'NumInt'), 'NumInt')
+      math.negate(math.complex(1.2, 2.8)) // TODO: make this call unnecessary
+      assert.strictEqual(
+         math.returnTypeOf('negate', 'Complex<number>'), 'Complex<number>')
+      assert.strictEqual(math.returnTypeOf('add', 'number,number'), 'number')
+      assert.strictEqual(math.returnTypeOf('add', 'NumInt,NumInt'), 'NumInt')
+      assert.strictEqual(math.returnTypeOf('add', 'NumInt,number'), 'number')
+      assert.strictEqual(math.returnTypeOf('add', 'number,NumInt'), 'number')
+      assert.deepStrictEqual(  // TODO: ditto
+         math.add(3, math.complex(2.5, 1)), math.complex(5.5, 1))
+      assert.strictEqual(
+         math.returnTypeOf('add', 'Complex<number>,NumInt'), 'Complex<number>')
+      // The following is not actually what we want, but the Pocomath type
+      // language isn't powerful enough at this point to capture the true
+      // return type:
+      assert.strictEqual(
+         math.returnTypeOf('add', 'number,NumInt,Complex<number>'), 'any')
+      assert.strictEqual(
+         math.returnTypeOf('chain', 'bigint'), 'Chain<bigint>')
+      assert.strictEqual(
+         math.returnTypeOf('returnTypeOf', 'string,string'), 'string')
+      assert.strictEqual(
+         math.returnTypeOf('conjugate', 'bigint'), 'bigint')
+      assert.strictEqual(
+         math.returnTypeOf('gcd', 'bigint,bigint'), 'bigint')
+      math.identity(math.fraction(3,5)) // TODO: ditto
+      assert.strictEqual(math.returnTypeOf('identity', 'Fraction'), 'Fraction')
+      assert.strictEqual(
+         math.returnTypeOf('quotient', 'bigint,bigint'), 'bigint')
+      math.abs(math.complex(2,1)) //TODO: ditto
+      assert.strictEqual(
+         math.returnTypeOf('abs','Complex<NumInt>'), 'number')
+      math.multiply(math.quaternion(1,1,1,1), math.quaternion(1,-1,1,-1)) // dit
+      const quatType = math.returnTypeOf(
+         'quaternion', 'NumInt,NumInt,NumInt,NumInt')
+      assert.strictEqual(quatType, 'Complex<Complex<NumInt>>')
+      assert.strictEqual(
+         math.returnTypeOf('multiply', quatType + ',' + quatType), quatType)
+      assert.strictEqual(math.returnTypeOf('isZero', 'NumInt'), 'boolean')
+      assert.strictEqual(
+         math.returnTypeOf('roundquotient', 'NumInt,number'), 'NumInt')
+      assert.strictEqual(
+         math.returnTypeOf('factorial', 'NumInt'), 'bigint')
+   })
+
    it('can subtract numbers', () => {
       assert.strictEqual(math.subtract(12, 5), 7)
-      //assert.strictEqual(math.subtract(3n, 1.5), 1.5)
+      assert.throws(() => math.subtract(3n, 1.5), 'TypeError')
    })
 
    it('can add numbers', () => {

test/complex/_all.mjs

@@ -39,8 +39,8 @@ describe('complex', () => {
    })
 
    it('checks for equality', () => {
-      assert.ok(math.equal(math.complex(3,0), 3))
-      assert.ok(math.equal(math.complex(3,2), math.complex(3, 2)))
+      assert.ok(math.equal(math.complex(3, 0), 3))
+      assert.ok(math.equal(math.complex(3, 2), math.complex(3, 2)))
       assert.ok(!(math.equal(math.complex(45n, 3n), math.complex(45n, -3n))))
       assert.ok(!(math.equal(math.complex(45n, 3n), 45n)))
    })
@@ -83,6 +83,7 @@ describe('complex', () => {
       assert.deepStrictEqual(
          math.multiply(q0, math.quaternion(2, 1, 0.1, 0.1)),
          math.quaternion(1.9, 1.1, 2.1, -0.9))
+      math.absquare(math.complex(1.25, 2.5)) //HACK: need absquare(Complex<number>)
       assert.strictEqual(math.abs(q0), Math.sqrt(2))
       assert.strictEqual(math.abs(q1), Math.sqrt(33)/4)
    })

test/core/_utils.mjs

@@ -0,0 +1,8 @@
+import assert from 'assert'
+import * as utils from '../../src/core/utils.mjs'
+
+describe('typeListOfSignature', () => {
+   it('returns an empty list for the empty signature', () => {
+      assert.deepStrictEqual(utils.typeListOfSignature(''), [])
+   })
+})

test/custom.mjs

@@ -135,13 +135,8 @@ describe('A custom instance', () => {
       assert.strictEqual(
          inst.typeMerge(3, inst.complex(4.5,2.1)),
          'Merge to Complex<number>')
-      // The following is the current behavior, since 3 converts to 3+0i
-      // which is technically the same Complex type as 3n+0ni.
-      // This should clear up when Complex is templatized
-      assert.strictEqual(inst.typeMerge(3, inst.complex(3n)), 'Merge to Complex')
-      // But types that truly cannot be merged should throw a TypeError
-      // Should add a variation of this with a more usual type once there is
-      // one not interconvertible with others...
+      assert.throws(
+         () => inst.typeMerge(3, inst.complex(3n)), TypeError)
       inst.install(genericSubtract)
       assert.throws(() => inst.typeMerge(3, undefined), TypeError)
    })

test/generic/_all.mjs

@@ -0,0 +1,20 @@
+import assert from 'assert'
+import math from '../../src/pocomath.mjs'
+
+describe('generic', () => {
+   it('calculates mean', () => {
+      assert.strictEqual(math.mean(1,2.5,3.25,4.75), 2.875)
+      assert.strictEqual(
+         math.returnTypeOf('mean', 'number,number,number,number'),
+         'number'
+      )
+   })
+   it('compares things', () => {
+      assert.strictEqual(math.larger(7n, 3n), true)
+      assert.strictEqual(
+         math.returnTypeOf('larger', 'bigint,bigint'), 'boolean')
+      assert.strictEqual(math.smallerEq(7.2, 3), false)
+      assert.strictEqual(
+         math.returnTypeOf('smallerEq', 'number,NumInt'), 'boolean')
+   })
+})

test/generic/fraction.mjs

@@ -92,4 +92,10 @@ describe('fraction', () => {
       assert.deepStrictEqual(math.square(tf), math.fraction(9/16))
    })
 
+   it('knows the types of its operations', () => {
+      assert.deepStrictEqual(
+         math.returnTypeOf('ceiling', 'Fraction'), 'Fraction')
+      assert.deepStrictEqual(
+         math.returnTypeOf('multiply', 'Fraction,Fraction'), 'Fraction')
+   })
 })

test/tuple/_native.mjs

@@ -8,14 +8,12 @@ describe('tuple', () => {
 
    it('does not allow unification by converting consecutive arguments', () => {
       assert.throws(() => math.tuple(3, 5.2, 2n), /TypeError.*unif/)
-      // Hence, the order matters in a slightly unfortunate way,
-      // but I think being a little ragged in these edge cases is OK:
       assert.throws(
          () => math.tuple(3, 2n, math.complex(5.2)),
          /TypeError.*unif/)
-      assert.deepStrictEqual(
-         math.tuple(3, math.complex(2n), 5.2),
-         {elts: [math.complex(3), math.complex(2n), math.complex(5.2)]})
+      assert.throws(
+         () => math.tuple(3, math.complex(2n), 5.2),
+         /TypeError.*unif/)
    })
 
    it('can be tested for zero and equality', () => {
@@ -56,6 +54,9 @@ describe('tuple', () => {
       assert.deepStrictEqual(
          math.subtract(math.tuple(3n,4n,5n), math.tuple(2n,1n,0n)),
          math.tuple(1n,3n,5n))
+      assert.deepStrictEqual(
+         math.returnTypeOf('subtract', 'Tuple<bigint>,Tuple<bigint>'),
+         'Tuple<bigint>')
       assert.throws(
          () => math.subtract(math.tuple(5,6), math.tuple(7)),
          /RangeError/)
@@ -106,9 +107,16 @@ describe('tuple', () => {
    })
 
    it('supports sqrt', () => {
+      const mixedTuple = math.tuple(2, math.complex(0,2), 1.5)
       assert.deepStrictEqual(
-         math.sqrt(math.tuple(4,-4,2.25)),
-         math.tuple(2, math.complex(0,2), 1.5))
+         mixedTuple,
+         math.tuple(math.complex(2), math.complex(0,2), math.complex(1.5)))
+      assert.strictEqual(
+         math.returnTypeOf('tuple', 'NumInt, Complex<NumInt>, number'),
+         'Tuple<Complex<number>>')
+      assert.deepStrictEqual(math.sqrt(math.tuple(4,-4,2.25)), mixedTuple)
+      assert.strictEqual(
+         math.returnTypeOf('sqrt', 'Tuple<NumInt>'), 'Tuple<Complex<number>>')
    })
 
 })