# @io-maana/typesystem-utils

> Maana Q Type System utilities

Latest version **1.0.9** (published 2021-02-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @io-maana/typesystem-utils
pnpm add @io-maana/typesystem-utils
yarn add @io-maana/typesystem-utils
bun add @io-maana/typesystem-utils
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.9 |
| Published | 2021-02-24 |
| First published | 2021-02-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 68.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | witt3rd, bzvetey, abatyuk, rpovey, teamcitymaana, dlsmaana |

## Links

- npm: https://www.npmjs.com/package/@io-maana/typesystem-utils
- npm.io page: https://npm.io/package/@io-maana/typesystem-utils

## Dependencies (3)

- [fp-ts](https://npm.io/package/fp-ts.md) ^2.1.2
- [io-ts](https://npm.io/package/io-ts.md) ^2.0.1
- [graphql](https://npm.io/package/graphql.md) ^14.4.2

## Recent versions

- 1.0.9 (latest) — 2021-02-24

## README

# Maana Q Typesystem Utils

Collection of utilities to work with Q type system, specifically with its Public API representation

# TypeExpression, Locator and Value Scalars

To use scalars, add them to your schema:

```
scalar Locator
scalar TypeExpression
scalar Value
```

and add them to your resolver map:

```
import { Locator, TypeExpression, Value } from 'typesystem-utils/scalars'

  ...
  Mutation: {
    ...FunctionResolver.Mutation,
    ...FunctionGraphResolver.Mutation,
    ...ServiceResolver.Mutation,
    ...TypeResolver.Mutation
  },
  Locator,
  TypeExpression,
  Value
```

You can also use `encodeLocator`, `decodeLocator`, `encodeTypeExpression` and `decodeTypeExpression`
functions directly for encoding and validation.

**Note**: To use this scalar, instances of model classes should be used, i.e. you must use
`const locator = new IDRefLocator({ id: "myTypeId" })` instead of `const locator = { id: "myTypeId"})`,
but as class constructors all receive an object with type properties, second constant can be used to
instantiate an object of required class:

```
import { IDRefLocator } from 'typesystem-utils'

const locatorObject = { id: "myTypeId"})
const locatorClassInstance = new IDRefLocator(locatorObject)
```

## Locator scalar

Convenience data structure that is used to uniquely identify referred entity, e.g. types and functions.
Locators can be used in type expressions to identify a type within a type expression, or to request
information about types or functions from catalog service's public API.

There are three types of locators:

### IDRefLocator

Locate entity (e.g. type or function) using its id.

**Model**

```
new IDRefLocator({id: "myTypeId"})
```

**Serialization**

```
{ "idRef": "myTypeId"}
```

### ServiceAndNameLocator
Locate entity (e.g. type or function) using its service id and name

**Model**

```
new ServiceAndNameLocator({ serviceId: "io.maana.catalog" name: "updateService" })
```

**Serialization**

```
{ "serviceAndName": { "serviceId": "io.maana.catalog", name: "updateService" }}
```

### LocalNameLocator

Locate entity (e.g. type or function) using its name within a local context,
e.g. in the service being added.

**Model**
```
new LocalNameLocator({ name: "ThatOtherType" })
```

**Serialization**

```
{ "localName": "ThatOtherType" }
```

## TypeExpression Scalar

Replacement for all types in Public API that are related to TypeExpression - i.e.:
* TypeExpression and its hierarchy
* TypeExpressionInput and its hierarchy
* Additionally, Locators for pointing to concrete type and function

In addition to scalar itself, this library exposes validation and serialization format, with following goals in mind:
* Serialization format should be concise (there's no need to include '__typename' like in GraphQL)
* At the same time, it must not be ambiguous, i.e. serialized type expression should have one and only one representation in JSON

### Model types and serialization format

Each type expression has JSON representation as one of the following variants or locator (see above):

#### ListType

Lists of values of specific type - equivalent to KindDB's 'LIST' modifier

**Model**:

```
new ListType({
  of: <other type expression>
})
```

**Serialization**:

```
{
  "listOf": <serialized inner type expression>
}
```

#### NonNullType

Non-nullable type - equivalent to KindDB's 'NONULL' modifier

**Model**:

```
new NonNullType({
  of: <other type expression>
})
```

**Serialization**:
```
{
  "nonNullOf": <serialized inner type expression>
}
```

#### TypeParameter

Type parameters are placeholders for types that will be determined from usage. For instance,
the function "isEmpty" that returns true if a list is empty, and false otherwise can be given a type:

```
  isEmpty( list: [ a ] ): Boolean
```

where "a" is a placeholder for the type of elements in the list. Types can contain multiple type parameters.
For example, the map function contains two type parameters that represent the type of elements in the source
and target lists:

```
  map( function: a -> b, list: [a] ): [b]
```

Type parameters are scoped to the definition in which they occur. The type parameter "a" that occurs in
isEmpty can be assigned a different type parameter "a" that occurs in the map function. Furthermore, two
different instances of a function can have different types assigned to their parameters. This allows us 
to define generic types and functions.

**Model**:

```
new TypeParameter({
  name: <name of type parameter>
})
```

**Serialization**:

```
{
  "typeParameter": "<name of type parameter>"
}
```

#### Scalar

Reference to a scalar type (note: current definition is somewhat vague - scalar type has only one field - id of the scalar type itself)

**Model**:

```
new Scalar({
  id: <id of the scalar type>
})
```

**Serialization**:

```
{
  "scalar": "<id of the scalar type>"
}
```

#### Sum

Sum type - one of multiple types.

**Model**:

```
new Sum({
  variants: [<... variant type expressions>]
})
```

**Serialization**:

```
{
  "sum": [<serialized variant type expressions>]
}
```

#### Product

Product type - combination ('product') of other types.

Contrary to other type systems, it is name-based rather than position-based,
as most of external interfaces use named fields; and it is easy to go from
position-based to name-based products, but opposite is hard.

**Model**:

```
new Product({
  fields: [
    { name: "<name of field>", description: "<optional description>", type: <type of a field> }
    ...
  ],
  extendable: <boolean flag if it is exact list of fields or there may be more>
})
```

**Serialization**:
```
{
  "product": {
    fields: [
      { name: "<name of field>", description: "<optional description>", type: <serialized type expression> }
    ],
    "extendable": <boolean>
  }
}
```

#### Function Type

Function Type is a Type Expression that allows using Functions as first-class values.

Arguments of a function are name-based rather than order-based, but as order of arguments matters for Type
System internals, it is guaranteed to be returned in the same order between updates.

If ordering matters in the future, Catalog will define API for changing order of fields without exposing 
actual ordinals.

**Model**:

```
new m.FunctionType({
  arguments: [
    { 
      id: "<id of a field>",
      name: "<name>",
      description: "optional descrption",
      type: <type of the argument>
    }
  ],
  resultType: <result type of a function>
})
```

**Serialization**:

```
{
  "function": {
    "arguments": [
      {
        "id": "<id>",
        "name": "<name>",
        "description": "description",
        "type": <serialized type expression>
      }
    ],
    "resultType": <serialized type expression>
  }
}
```


#### Enum Type

Enum type is a type expression that allows a finite defined set of values of the same type.

**Model**:

```
new m.Enum({
    of: new ServiceAndNameLocator({ serviceId: 'io.maana.core', name: 'String' }),
    values: [
      new StringValue({ value: 'A' }),
      new StringValue({ value: 'B' }),
      new StringValue({ value: 'C' })
    ]
  })
```

**Serialization**:

```
{
  "enum": {
    "of": {
      "serviceAndName": {
        "serviceId": "io.maana.core",
        "name": "String"
      }
    },
    "values": [
      { "string": "A" },
      { "string": "B" },
      { "string": "C" }
    ]
  }
}
```

### Examples

All of the examples above mention `<serialized type expression>` to describe nested types, example:

Type Promise is generic over type of value V, with two fields - indicator if promise is ready, and a function
to get value.

Type defined in a model:

```
const promiseType = new Product({
    fields: [
      {
        name: 'isReady',
        type: new NonNullType({ of: new Scalar({ id: 'Boolean' })}) 
      },
      {
        name: 'getValue',
        type: new FunctionType({
          arguments: [],
          resultType: new TypeParameter({ name: 'V'})
        })
      }
    ],
    extendable: false
  })
```

Serialized format:

```
{
  "product": {
    "fields": [
      { "name": "isReady", "type": { "nonNullOf": { "scalar": "Boolean" } } },
      {
        "name": "getValue",
        "type": {
          "function": {
            "arguments": [],
            "resultType": { "typeParameter": "V" }
          }
        }
      }
    ],
    "extendable": false
  }
}
```

References to types and functions are done using Locators, for instance, following is simplicitic definition of services,
based on (non-existent at the moment) types Function and Type defined in 'io.maana.core' service:

Model:

```
const IDScalar = new Scalar({ id: 'ID '})
const StringScalar = new Scalar({ id: 'String' })

const FunctionTypeRef = new ServiceAndNameLocator({ name: 'Function', serviceId: 'io.maana.core' })
const TypeTypeRef = new ServiceAndNameLocator({ name: 'Type', serviceId: 'io.maana.core' })

const logicServiceType = new Product({
  extendable: false,
  fields: [
    { name: 'id', type: IDScalar },
    { name: 'functions', type: new ListType({ of: FunctionTypeRef })},
    { name: 'types', type: new ListType({ of: TypeTypeRef })}
  ]
})

const externalServiceType = new Product({
  extendable: false,
  fields: [
    { name: 'endpointUrl', type: StringScalar },
    { name: 'graphQLSchema', type: StringScalar }
  ]
})

const serviceType = new Sum({
  variants: [
    logicServiceType,
    externalServiceType
  ]
})
```

Serialized format:

```
{
  "sumOf": [
    {
      "product": {
        "fields": [
          { "name": "id", "type": { "scalar": "ID " } },
          {
            "name": "functions",
            "type": {
              "listOf": { "serviceAndName": { "serviceId": "io.maana.core", "name": "Function" }
              }
            }
          },
          {
            "name": "types",
            "type": {
              "listOf": { "serviceAndName": { "serviceId": "io.maana.core", "name": "Type" }}
            }
          }
        ],
        "extendable": false
      }
    },
    {
      "product": {
        "fields": [
          { "name": "endpointUrl", "type": { "scalar": "String" } },
          { "name": "graphQLSchema", "type": { "scalar": "String" } }
        ],
        "extendable": false
      }
    }
  ]
}
```

## Type expression traversals

This package also exposes two functions that make type expression interrogation and modification easier, `traverseTypeExpression` and `traverseTypeExpressionAsync`.
These functions take a list of callbacks for specific type expression types, type expression, and produce a type expression that applied callbacks to all type expressions,
recursively.

Mapper has the following shape (async version takes async functions as arguments):
```
type TraverseMapper = {
  onIDRefLocator?: (te: IDRefLocator) => TypeExpression
  onLocalNameLocator?: (te: LocalNameLocator) => TypeExpression
  onServiceAndNameLocator?: (te: ServiceAndNameLocator) => TypeExpression
  onScalar?: (te: Scalar) => TypeExpression
  onListType?: (te: ListType) => TypeExpression
  onNonNullType?: (te: NonNullType) => TypeExpression
  onProduct?: (te: Product) => TypeExpression
  onSum?: (te: Sum) => TypeExpression
  onTypeParameter?: (te: TypeParameter) => TypeExpression
  onFunctionType?: (te: FunctionType) => TypeExpression
  onEnumType?: (te: Enum) => TypeExpression
}
```

### Usage examples

Traverse type expression recursively and collect all locators, without modification of original type expression

```
export function extractLocatorsFromTypeExpression(typeExpression: tsutils.TypeExpression): tsutils.Locator[] {
  const locators: tsutils.Locator[] = []

  function addLocator(locator: tsutils.Locator): tsutils.Locator {
    locators.push(locator)
    return locator
  }

  traverseTypeExpression(typeExpression, {
    onIDRefLocator: addLocator,
    onServiceAndNameLocator: addLocator,
    onLocalNameLocator: addLocator
  })

  return _.uniqWith(locators, _.isEqual)
}
```

Rewrite all IDRefLocators with ServiceAndNameLocators

```
export async function rewriteIdRefToSnNLocator(te: tsutils.TypeExpression, store: Store) {
  return traverseTypeExpressionAsync(te, {
    onIDRefLocator: async (loc) => {
      const type = await store.type(loc)
      return type ? new tsutils.ServiceAndNameLocator({ serviceId: type.serviceId, name: type.name }) : new tsutils.ServiceAndNameLocator({
        serviceId: "Unknown service",
        name: JSON.stringify(tsutils.encodeTypeExpression(loc))
      })
    }
  })
}
```

---
_Source: https://npm.io/package/@io-maana/typesystem-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._