Item Specifications

Table of Contents

Map-like object indexed by identifier and types

This page is devoted to concepts and designs for the structure of items in the TypeDispatcher and how they are specified.

Map-like object indexed by identifier and types

In this concept, we think of the TypeDispatcher object math simply as a big map indexed by a string identifier and a list of types. Since those are complicated non-string and non-number "indices", which JavaScript doesn't really handle gracefully, we provide the basic indexing method math.resolve('foo', [T1, T2, ..., Tn]), with a handful of special properties:

The math object is set up so that you can write math.foo(a, b, c) rather than math.resolve('foo', [math.typeOf(a), math.typeOf(b), math.typeOf(c)])(a, b, c). For values that are functions, we should also be able to write math.foo.resolve(T1, T2, T3).
The stored entities are "dependent objects" -- they record at their creation time what other entries of the TypeDispatcher object they depend on, and if any of those change, they are regenerated as needed.
The keys and values of the math object can be specified in a pattern-matching style that supports/simulates generic functions

How would this look in practice? Let's start by considering a square function that can operate on any type and depends on the multiply entry for that same type, and just calls that entry with both arguments set to the original single argument. We might specify this as:

export const square = (math, [T]) => {
   const mul = math.multiply.resolve(T, T)
   return a => mul(a, a)
}

Note that we should not write

export const square = (math, [T]) => {
   return a => math.multiply(a, a)
}

That's because in order to work as a dependency, the dependent items must be extracted within the factory for the item, not within the behavior that the factory returns.

There's another wrinkle; we want to record the return type of all of the methods, both for writing TypeScript type definition files and for making it easier to select the best implementations for other methods. So we will really need to write something like:

export const square = (math, [T]) => {
   const mul = math.multiply.resolve(T, T)
   return Returns(mul.returns, a => mul(a, a))
}

This seems a trifle "heavy" but I'm not seeing clear ways at the moment to streamline it.

Note the above implementation of square works for all types, so there is not any type matching going on in the definition. (Presumably this creates a fallback universal implementation, and you could still add specialized implementations, say on a Boolean argument.) So let's take a look at what we would have to do for the multiply implementation on two numbers -- a plain function with no dependencies. Something like

export const multiply = onType([Number, Number], Returns(Number, (a, b) => a * b))

Here, onType creates an "Implementation," which consists of one or more "type patterns" (an array of types/type predicates to match against the actual arguments) with associated behaviors, which can be exported to produce partial definitions for a method: a behavior will be executed when the argument types match its associated pattern. The fact that here the behavior is return-type-labeled indicates that the item has no dependencies. There is a separate page devoted to the details of implementations and type patterns.

Next, let's look at a method like addition of two complex numbers that accepts many types (any instantiation of Complex) but not all types, and has dependencies:

export const add = onType([Complex, Complex], (math, [T, U]) => {
   const add = math.add.resolve(T.Base, U.Base)
   const complex = math.complex.resolve(add.returns, add.returns)
   return Returns(
      complex.returns,
      (w, z) => complex(add(w.re, z.re), add(w.im, z.im))
   )
})

Note that the Complex types in the signature specification are not "ground" types -- they are generic types, and so serve as patterns that say that this export specifies the value for any two-entry signature in which each entry is an instance of complex. We then get the actual call types T and U in the factory function -- they could conceivably be Complex(BigInt) and Complex(Number), say. Any two complex types will be fine, so long as we can add their base types, which we will discover when we try to fetch the add implementation on those two types.

Putting a few features together, consider sqrt of a number, which produces different implementations depending on what types are available and the configuration:

// don't bother with the signature argument in the factory, since we know it's [Number]
export const sqrt = onType(Number, math => {
   if (math.config.predictable || !math.types.Complex) {
      return Returns(Number, Math.sqrt)
   }
   const complex = math.complex.resolve(Number, Number)
   return Returns(
      Union(Number, Complex(Number)),
      a => n < 0 ? complex(0, Math.sqrt(-a)) : Math.sqrt(a)
   )
}

Note here that ideally the accesses to math.config.predictable and math.types.Complex in this factory mean that the resulting implementation of sqrt will depend on the predictable property of math.config, and so only be invalidated when that property changes, not on any change to math.config, just the way that the other possible implementation would only be invalidated if the implementation of complex on Number, Number were updated, but unaffected if the implementation of complex on BigInt, BigInt changed. Also note the convenience that for unary signatures, you can supply just a type; you don't have to put it in braces.

Looking at how other config properties might work, let's suppose that the constants property gives the numeric type that should be used for named constants (e.g., Number or BigNumber). We want math.tau to give a scalar entity, but we'd also like to record different possible entities for different types. Since we can't put properties on a number, we use a resolve function directly on the math object that takes the identifier to resolve:

export const tau = onType(
   Number, 6.2831853,
   BigNumber, math => math.bignumber('6.28318530717958647692'),
   [], math => math.resolve('tau', [math.config.constants])
)

A few things to note in this example: now clients of the eventual bundle can use math.resolve('tau', math.BigNumber) to get the BigNumber value of tau regardless of the current type in the config.constants setting, the plain math.tau should resolve to the correct scalar entity, and the plain math.tau should be reset if either config.constants changes or if the setting of math.tau on the type config.constants changes.

Finally, let's see how the troubling example of absquare in glen/pocomath#55 would pan out:

export const absquare = onType(Complex, (math, [T]) => {
   const absq = math.absq.resolve(T.Base)
   const add = math.add.resolve(absq.returns, absq.returns)
   return Returns(add.returns, z => add(absq(z.re), absq(z.im))
})

This seems like a success of this scheme to me. Hence, the current plan is to recast the prototype into this format.