DEV Community: Nick Kelly

JavaScript Inheritance: The Dark Arts

Nick Kelly — Tue, 25 May 2021 00:42:22 +0000

Inheritance remains one of the most relied upon and misunderstood features of JavaScript to this day. Since ES2015 JavaScript developers have been able to ignore how the inheritance sausage is made by relying on the class syntax that hides the nitty gritty details, until they run into its mind-bending edge cases.

In this post we'll explore the secrets of JavaScript inheritance: [[Prototype]] and constructors.

But first, put your knowledge to the test:

How many can you get right?

1. Overriding getters and setters

console.log('Overriding getters and setters');

class SuperClass {
  _value = undefined;
  get value() { return this._value; }
}
class SubClass extends SuperClass {
  set value(to) { this._value = to; }
}
const sub = new SubClass();
sub.value = 5;

// What gets logged?

console.log(sub.value); // undefined

2. Deleting from a class instance

console.log('Deleting from a class instance');

class MyClass {
  fn1 = function() {}
  fn2() {}
}
const myInstance = new MyClass();

// What gets logged?

delete myInstance.fn1;
console.log(myInstance.fn1); // undefined

delete myInstance.fn2;
console.log(myInstance.fn2); // fn2() {}

3. Deleting from an object

console.log('Deleting from an object');

const myObject = {
  fn() {},
  toString() {},
};

// What gets logged?

delete myObject.fn;
console.log(myObject.fn); // undefined

console.log(myObject.toString); // toString() {}
myObject.toString = undefined
console.log(myObject.toString); // undefined
delete myObject.toString;
console.log(myObject.toString); // toString() { [native code] }

4. Overriding constructors???

class MyClass {
  constructor() {
    console.log("Original Consturctor");
  }
}

MyClass.prototype.constructor = function Overridden() {
  console.log("Overridden Constructor");
}

// What gets logged?

const instance = new MyClass(); // "Original Constructor"
console.log(instance.constructor.name);  // Overridden
console.log(instance.constructor.prototype === Object.getPrototypeOf(instance)); // false

If you got all of the above right then maybe you're already grizzled JavaScript veteran and know all the ins and outs of OOJS (Object Oriented JavaScript).

For the rest of us, it's time to open Pandora's Box.

Inheritance

In OOP (Object Oriented Programming), inheritance is the mechanism used build a new object or class ontop another object or class.

JavaScript has inheritance but doesn't have static "classes" like static OO languages (C++, C#, Java). Instead, JavaScript links objects together by prototypes. Even in ES2015, class is mostly just syntactic sugar for objects with prototypal relationships.

At a glance, OOJS using class appears sane.

class Base {
  prop = 'hello world';
}
class Sub extends Base {
  //
}
const sub = new Sub();
// sub has access to properties on base
console.log(sub.prop);  // "hello world"

But how does this really work? What is a "class" and how does sub have access to prop?

Enter: [[Prototype]]

JavaScript uses prototypes to achieve inheritance. All objects have a [[Prototype]] internal slot which is the object being inherited from. Internal slots are internal to the JavaScript interpreter. Some internal slots are exposed via functions like Object.getPrototypeOf() and many aren't exposed at all.

An object's [[Prototype]] can be null or another object which itself has a [[Prototye]] slot. An object's linked list of [[Prototype]]s (i.e. myObject.[[Prototype]].[[Prototype]].[[Prototype]]...) is called its "prototype chain" and terminates with null.

To lookup a property on an object the JavaScript interpreter performs a lookup on the top-level object, then that object's [[Prototype]], then [[Prototype]].[[Prototype]], and so on until reaching null.

We can use Object.create(proto) to create a new object with proto as its [[Prototype]] and use Object.getPrototypeOf(obj) to get the [[Prototype]] of an object obj

const ancestor = Object.create(null);
const parent = Object.create(ancestor);
const child = Object.create(parent);

// child inherits from parent
console.log(Object.getPrototypeOf(child) === parent); // true
// parent inherits from ancestor
console.log(Object.getPrototypeOf(parent) === ancestor); // true
// ancestor inherits nothing
console.log(Object.getPrototypeOf(ancestor) === null); // true

We can also use Object.setPrototypeOf(sub, base) to change the [[Prototype]] of an object sub to another object (or null), base. Notice - unlike static OO languages we can dynamically change inheritance heirarchies at runtime! For performance reasons this is strongly advised against. According to Benedikt Muerer of v8, a every time you change the prototype chain, a kitten dies.

const base = { prop: 'hello world' };
const sub = {};
console.log(sub.prop); // undefined
Object.setPrototypeOf(sub, base);
console.log(sub.prop); // "hello world"
Object.setPrototypeOf(sub, null);
console.log(sub.prop); // undefined

Objects created using the object literal syntax {} inherit from JavaScript's base Object.prototype which in-turn inherits from null.

const obj = {};
console.log(Object.getPrototypeOf(obj) === Object.prototype); // true
console.log(Object.getPrototypeOf(Object.prototype) === null); // true

Functions

Functions are a regular JavaScript objects, but with additional internal slots. Like regular objects they have properties and a [[Prototype]] internal slot, but unlike other objects they are callable thanks to a [[Call]] internal method.

Constructors are functions with some specific attributes.

Enter: Constructors

Constructor functions compliment prototypes by making prototype configuration and object creation and inialisation easy and consistent. Inheritance can still be achieved without constructors (for example with Object.create) but it's less common.

Any non-arrow function (any function created with the function keyword) can be used as a constructor. All non-arrow functions have a prototype property, initialized to a new object with only one property prototype.constructor whose value is the constructor function. Note that a function's prototype property is NOT the same as that functions [[Prototype]] internal slot.

Constructors have to be called with a the new operator (unless being used within another constructor function for inheritance) for the this variable to be created and bound correctly. The this object's [[Prototype]] is set to the constructors prototype property.

It's good practice to begin constructor names with an uppercase character so you know to call them with new.

function Constructor() {} 
console.log(Constructor.prototype); // { constructor: f }
const instance = new Constructor();
console.log(Object.getPrototypeOf(instance) === Constructor.prototype) // true
// i.e. instance.[[Prototype]] === Constructor.prototype

When called with new, construtors implicitly return their this object.

let this_ref;

function Constructor() {
  console.log(Object.getPrototypeOf(this) === Constructor.prototype); // true
  this_ref = this;
  // implicitly returns `this`
}

const that = new Constructor();
console.log(that === this_ref); // true;

"classes" created with the ES2015 (e.g. class MyClass {...}) are also simply constructor functions (typeof MyClass === 'function') but whose internal slots are configured differently, such as [[IsClassConstructor]] that causes classes to throw a TypeError if called without the new operator, unlike constructor functions not created with the class syntax.

Given that instances created with the new operator inherit from their constructors prototype property, we can create functions on the prototype property that will be inherited by the instances.

function Person() {
  //
}

Person.prototype.sayHello = function() {
  console.log('hello');
}

const person = new Person();
person.sayHello();  // 'hello'

ES2015 classes without ES2015 syntax

Now that we know about prototypes and constructors we can replicate the ES2015 class functionality with constructor functions and prototypes.

Using constructor-prototype syntax we have enormous flexibility in how we glue together our objects at the price of having to glue them together manually.

We can manually accomplish what the ES2015 class syntax does for us by maintaining the following:

Instance prototype chain: SubClass.prototype.[[Prototype]] must be set to SuperClass.prototype. This sets up the prototype chain of instances constructed from new SubClass(...) such that:
- subclass_instance.[[Prototype]] === SubClass.prototype
- subclass_instance.[[Prototype]][[Prototype]] === SuperClass.prototype
- subclass_instance.[[Prototype]][[Prototype]][[Prototype]] === Object.prototype
- subclass_instance.[[Prototype]][[Prototype]][[Prototype]][[Prototype]] === null
Constructor prototype chain: SubClass.[[Prototype]] must be set to SuperClass. This means the SubClass function inherits "static" properties from SuperClass (properties on the SuperClass constructor function) such that:
- SuperClass.staticProperty = 5
- SubClass.staticProperty === 5
Initialisation: When the SubClass constructor is called with new, it needs to immediately call the SuperClass constructor function binding its this value (SuperClass.call(this, ...)), in order to initialise SuperClass on this properly.
- The ES2015 class syntax forces us to call the super constructor using super() at the beginning of our subclasses constructor function, or else the interpreter will throw an error. This is not forced in constructor-prototype syntax so we need to remember it ourselves! Otherwise our class instances will not be properly initialised.

Our object relations for the model described above are:

Don't be intimidated by the number of objects and connections - if you can grok the diagram then you can derive an understanding of everything relating OOJS.

The `super` Problem

The only class functionality we can't exactly replicate with constructors and prototypes is super.

function Base() {}
Base.prototype.fn = function() {
  console.log('base');
}

function AnotherBase() {}
AnotherBase.prototype.fn = function() {
  console.log('another base');
}

function Sub() {}
Object.setPrototypeOf(Sub, Base);
Sub.prototype.fn = function() {
  console.log('sub');
  // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  // "super" call, hardcoded to `Base`
  // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  Base.prototype.fn.call(this);
}

const sub = new Sub();

sub.fn();
// sub
// base

Object.setPrototypeOf(Sub, AnotherBase);
Object.setPrototypeOf(Sub.prototype, AnotherBase.prototype);
sub.fn();
// sub
// base

Without referencing the superclass, Base, directly we have no way to determine where the current method under invocation sits in the prototype chain, and therefore can't lookup functions that are strictly higher in the prototype chain (i.e. a super call).

By referencing Base directly in an attempt to replicate super, we've destroyed our ability to safely change the prototype since our "super" call would be referencing a function we no longer inherit.

With ES2015, we have a super keyword that still works when we reassign [[Prototype]]

class Base {
  fn() {
    console.log('base');
  }
}

class AnotherBase {
  fn() {
    console.log('another base');
  }
}

class Sub extends Base {
  fn() {
    console.log('sub');
    super.fn();
  }
}

const sub = new Sub();

sub.fn();
// sup
// base

Object.setPrototypeOf(Sub, AnotherBase);
Object.setPrototypeOf(Sub.prototype, AnotherBase.prototype);

sub.fn();
// sup
// another base

Pre ES2015 classes by example

We'll code a simple inheritance example of 2 classes: a superclass Animal and subclass Dog using the relations described above. Each inheritance layer has 3 associated objects: the constructor function, prototype object and instance object.

Our domain is:

In JavaScript, our objects will be:

/**
 * @constructor Animal
 * @abstract
 *
 * @param {number} legs
 */
function Animal(legs) {
  this.legs = legs;
}

/**
 * Abstract static property on Animal constructor
 * to be overridden by a property the subclasses constructor
 *
 * @abstract
 * @static
 * @type {string}
 */
Animal.species = undefined;

/**
 * getter on the animal prototype that retrieves the static, overridden
 * property from the subclasses constructor, `species`
 * 
 * @readonly
 * @type {string}
 * 
 * @example
 * const dog = new Dog()
 * dog.species; // calls `Animal.prototype.species` -> `Dog.species`
 */
Object.defineProperty(Animal.prototype, 'species', {
  enumerable: true,
  configurable: false,
  /** @returns {string} */
  get() {
    // alternatively, `const SubClass = this.constructor`
    const SubClass = Object.getPrototypeOf(this).constructor;
    return SubClass.species;
  },
})

/**
 * Method on the Animal prototype, inherited by animal instances and subclasses
 * of Animal
 *
 * @param {string} food
 */
Animal.prototype.eat = function(food) {
  console.log(`Yum! eating ${food}`);
}


/**
 * @constructor Dog
 *
 * Subclass of Animal
 */
function Dog() {
  const legs = 4;

  // we run the inherited constructor, bound to `this`, to initialise our superclass properly
  // this effectively "subtypes" `this` to an instance of the superclass (`this` becomes a superset of the superclasses instances type)

  Animal.call(this, legs);
}

// Inherit staticically from Animal
Object.setPrototypeOf(Dog, Animal);

// Inherit prototype from Animal
Object.setPrototypeOf(Dog.prototype, Animal.prototype);

/**
 * @override
 * @type {string}
 */
Dog.species = 'Dog';

/**
 * Override the `eat` method from `Animal.prototype`
 * Also call the super method
 *
 * @override
 *
 * @param {*} food
 */
Dog.prototype.eat = function(food) {
  console.log('Woof!');

  // super call!
  Animal.prototype.eat.call(this, food);
}

const dog = new Dog();

dog.eat('chicken');
// 'Woof!'
// 'Yum! eating chicken'

console.log(dog.species);
// 'Dog'

Access to inherited properties

One of the most important things to understand when working directly with prototypes is how accessors and operators propagate. Of the following actions, only the get accessor propagates up the prototype chain.

accessor or operator	propagates up the prototype chain
get	yes
set	no
delete	no

const base = { prop: 'hello', ref: {} };
const sub = {};
Object.setPrototypeOf(sub, base);
console.log(sub.prop); // 'hello'

// the `delete` operator does not propagate

// calling delete on `prop` can have no effect on objects in its prototype chain
delete sub.prop;
console.log(sub.prop); // 'hello'

// similarly, the `set` accessor does not propagate
console.log(sub.ref === base.ref); // true
base.ref = { a: 'different', object: true };
console.log(sub.ref === base.ref); // true
sub.ref = { something: 'else' };
console.log(sub.ref === base.ref); // false

Who cares?

Most JavaScript application developers don't need to know its inheritance mechanism in great detail. Some of JavaScript's most flexible features, including prototype hacking, are considered footgun's to be avoided. If you feel the need to hack a prototype chain you're probably better off finding another way.

Knowing about prototypes is more important when working in the broader ecosystem with packages or tooling or when monkeypatching libraries (modifying prototypes of objects from third party libraries).

How does TypeScript fit into this?

Unfortunately, like a square peg into a round hole.

TypeScript doesn't attempt to model the fine details of OOJS. It doesn't differentiate between properties on a class instance and properties on a classes prototype.

class MyClass {
  instanceProperty: number;
  prototypeProperty() {};
  constructor() { this.instanceProperty = 5; }
}

// TypeScript sees instances of MyClass as equivalent to:
interface MyClassInstance {
  instanceProperty: number;
  prototypeProperty() {};
}
// properties of the prototype and instance are merged together

Moreover, TypeScript doesn't even allow adding new signature to a constructor function.

const MyConstructor: { new(): {} } = function() {}
// Type '() => void' is not assignable to type 'new () => {}'.

To use TypeScript on constructor functions have to resort to the unsafe as unknown hack. The language server also won't tell us when our prototype is missing properties

interface MyInstanceAndPrototype {
  //
  methodOnPrototype() {};
}

interface MyConstructor extends Function {
  new(): MyInstanceAndPrototype;
  prototype: MyInstanceAndPrototype;
}

const MyConstructor = function MyConstructor() {} as unknown as MyConstructor

// Forgot to add `MyConstructor.prototype.methodOnPrototype`?
// There won't be any TypeScript error

Revisiting our examples

With our understanding of prototypes, constructors and property access, we can revisit our and understand initial examples

Explanation: 1. Overriding getters and setters

console.log('Overriding getters and setters');

class SuperClass {
  _value = undefined;
  get value() { return this._value; }
}
class SubClass extends SuperClass {
  set value(to) { this._value = to; }
}
const sub = new SubClass();
sub.value = 5;

// What gets logged?

console.log(sub.value); // undefined

What went wrong?

Writing this in pre-ES2015 syntax we have something close to:

console.log('Overriding getters and setters');

function SuperClass() {
  this._value = undefined;
}
Object.defineProperty(SuperClass.prototype, 'value', {
  get() { return this._value },
})

function SubClass() {}

Object.setPrototypeOf(SubClass, SuperClass);
Object.setPrototypeOf(SubClass.prototype, SuperClass.prototype);

Object.defineProperty(SubClass.prototype, 'value', {
  set(to) { this._value = to; },
});

const sub = new SubClass();

sub.value = 5;

// What gets logged?

console.log(sub.value); // undefined

Notice we have both SubClass.prototype.value and SuperClass.prototype.vaue.
SubClass.prototype.value overrides SuperClass.prototype.value. SubClass.prototype.value has a setter with NO GETTER!! When we read sub.value, we accessing SubClass.prototype.value which has no getter and a value of undefined by default, and therefore returns undefined. We never reach SuperClass.prototype.value! This issue once cost me 4 hours in debugging hell.

Explanation: 2. Deleting from a class instance

console.log('Deleting from a class instance');

class MyClass {
  fn1 = function() {}
  fn2() {}
}
const myInstance = new MyClass();

// What gets logged?

delete myInstance.fn1;
console.log(myInstance.fn1); // undefined

delete myInstance.fn2;
console.log(myInstance.fn2); // fn2() {}

Writing this in pre-ES2015 syntax we have something close to:

console.log('Deleting from a class instance');

function MyClass() {
  this.fn1 = function() {};
}
MyClass.prototype.fn2 = function fn2() {}

const myInstance = new MyClass();

// What gets logged?

delete myInstance.fn1;
console.log(myInstance.fn1); // undefined

delete myInstance.fn2;
console.log(myInstance.fn2); // fn2() {}

Notice that with class syntax, setting property = ... within the class body is roughly equivalent setting this.property = ... within the classes constructor. It places the property on the class instances.

Conversely, fn2() {} within the class body adds that function to the classes prototype MyClass.prototype.

The delete operator does not propagate up the prototype chain. Therefore we delete fn1 since its on the class instance, but not fn2 since it's on the class prototype.

Explanation: 3. Deleting from an object

console.log('Deleting from an object');

const myObject = {
  fn() {},
  toString() {},
};

// What gets logged?

delete myObject.fn;
console.log(myObject.fn); // undefined

console.log(myObject.toString); // toString() {}
myObject.toString = undefined
console.log(myObject.toString); // undefined
delete myObject.toString;
console.log(myObject.toString); // toString() { [native code] }

Similar to 2., but now we have an object instance myObject with two functions. All objects created with the literal syntax {} have their [[Prototype]] equal to Object.prototype. Object.prototype has a toString method.

In our example:

we override Object.prototype.toString in the assignment of myObject.
- logging myObject.toString prints our overridden copy, toString() {}
we set myObject.toString = undefined, which continues to override Object.prototype.toString but now with a value of undefined.
- logging myObject.toString prints our overridden copy, undefined
we delete toString from myObject. now toString calls will propagate up the prototype chain.
- logging myObject.toString prints Object.prototype.toString.

Explanation: 4. Overriding constructors???

class MyClass {
  constructor() {
    console.log("Original Consturctor");
  }
}

MyClass.prototype.constructor = function Overridden() {
  console.log("Overridden Constructor");
}

// What gets logged?

const instance = new MyClass(); // "Original Constructor"
console.log(instance.constructor.name);  // "Overridden Constructor"
console.log(instance.constructor.prototype === Object.getPrototypeOf(instance)); // "false"

This example is bogus. A special place in hell is reserved for people who reassign Constructor.prototype.constructor.

Constructors have a prototype property which becomes their instances [[Prototype]] internal slot.
The prototype initially has a single property, constructor, which points back to the original constructor function.
The Constructor.prototype.constructor is useful to superclasses to create new instances of this's class.

For example, here's a Container class that is safe to extend and still call clone() on:

function Container(items) {
  this.items = items;
}
Container.prototype.clone = function() {
  // we rely on prototype.constructor not being overridden
  return new (Object.getPrototypeOf(this).constructor)([...this.items]);
}

function UserContainer(users) {
  Container.call(this, users);
}
Object.setPrototypeOf(UserContainer, Container);
Object.setPrototypeOf(UserContainer.prototype, Container.prototype);
UserContainer.prototype.logoutAll = function() { /** ... */ }

const users = new UserContainer([]);
const users2 = users.clone();
console.log(users2 instanceof UserContainer); // true

As far as I'm aware there's no good reason to ever change prototype.constructor, other than as a good April Fools joke.

UPDATE 2021-08-11

It turns out some people DO reassign or override the constructor property.

Take a look at this example from webpack's library for events/hooks/callbacks, Tapable.

// https://github.com/webpack/tapable/blob/v2.2.0/lib/SyncHook.js#L37
function SyncHook(args = [], name = undefined) {
  const hook = new Hook(args, name);
  hook.constructor = SyncHook;
  hook.tapAsync = TAP_ASYNC;
  hook.tapPromise = TAP_PROMISE;
  hook.compile = COMPILE;
  return hook;
}

Calling new SyncHook() returns an instance of Hook with a constructor property set to SyncHook. The new instances property, hook.constructor, overrides the inherited property, Hook.prototype.constructor, such that hook.constructor === SyncHook. However, hook instanceof SyncHook is false.

Just don't ask me why!

Writing a GraphQL TypeScript Server for NodeJS

Nick Kelly — Mon, 14 Dec 2020 14:17:56 +0000

Writing a GraphQL TypeScript Server for NodeJS

GraphQL is becoming an increasingly viable alternative to REST in modern web development by providing significant productivity and performance advantages.

In this post we will explore some important parts of writing a NodeJS code-first vanilla GraphQL Server in TypeScript.

This is for

People who understand the basics of GraphQL and want to see some patterns, techniques and different non-decorator approaches to building a GraphQL server in TypeScript.

This is not

A complete front-to-back tutorial.

You will see important code snippets and fill in the blanks with the rest of your stack.

Final result:

For the complete example server code, visit the GitHub.

GraphiQL

Partial Schema

Supported queries

A GraphQL server built with the architecture outlined below will support queries and mutations such as:

fragment PageInfoFragment on PageInfo{ page pages count total more }

# Find many Accounts
query FindAccounts {
  accounts(query:{limit:2 offset:0 sorts:[ { field:"id", dir: Asc } ]}){
    # collection of (first 2) accounts (sorted by id)
    pageInfo { ...PageInfoFragment }
    can { show create }
    nodes {
      # an account
      can { show withdraw deposit }
      data { id name balance }
      relations {
        # account has many transactions
        transactions(query:{ sorts:[{ field: "amount", dir: Desc }]}){
          # collection of transactions (sorted by amount)
          pageInfo { ...PageInfoFragment }
          can { show }
          nodes {
            can { show }
            data { id description amount }
          }
        }
      }
    }
  }
}

# Deposit into an Account
mutation Deposit {
  deposit(dto:{ account_id:1 amount:999999 }) {
    data { id name balance }
    relations{
      transactions(query: { sorts: [{ field: "id", dir: Desc }] }) {
        nodes{
          data{ id, description, amount }
        }
      }
    }
  }
}

# Withdraw from an Account
mutation Withdraw {
  deposit(dto:{ account_id:1 amount:20 }) {
    data { id name balance }
    relations{
      transactions(query: { sorts: [{ field: "id", dir: Desc }] }) {
        nodes{
          data{ id, description, amount }
        }
      }
    }
  }
}

Background

Code-first: decorators vs objects

Most popular guides use experimental / to-be-deprecated TypeScript (ES6) Decorators which obscure the GraphQL resolution process by merging the ORM layer with the API and the API layer with the authorisation layer.

Instead of Decorators, we will use the primitives provided by the graphql npm package. Most importantly: GraphQLObjectType and GraphQLInputType. These primitives are powerful enough to build a highly expressive and flexible GraphQL API.

GraphQL as the Engine of Application State

HATEOAS (Hypertext as the Engine of Application State) is an important part of the rest standard.

In practice, HATEOAS means the server should publish client-resource authorisation and routing to minimise code duplication on the client. A resource response should contain authorisation and link metadata.

HTTP/1.1 200 OK
Content-Type: application/vnd.acme.account+json
Content-Length: ...

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "links": {
            "deposit": "/accounts/12345/deposit",
            "withdraw": "/accounts/12345/withdraw",
            "transfer": "/accounts/12345/transfer",
            "close": "/accounts/12345/close"
        }
    }
}

GraphQL makes this easier than REST since GraphQL APIs often served off a single URL removing the need for "links". Furthermore, GraphQL's introspective type system lets developers circumvent API docs.

Leveraging Query Resolution to Create Flexible Graphs

Understanding how GraphQL resolves queries by separating Type and Source lets us build flexible and well-separated JSON structures.

A GraphQL server resolves a query by traversing the GraphQLObjectType tree to build a JSON response. However, the Source returned from a resolver need not of similar shape as the resolving GraphQLObjectType.

For example, a GraphQLObjectType that resolves an Account would typically resolve all fields, relations, and metadata on the same GraphQLObjectType node. Although, having separated our ORM layer from our GraphQL layer (something a Decorator based approach would obscure), we can separate an Account into multiple GraphQLObjectTypes representing an Accounts different categories of data, such as AccountData (the fields on an accounts table in the database), AccountActions (G|HATEOAS / action authorisation for the Account resource), AccountRelations (or AccountConnections), and additional objects for any additional categories of data associated with an Account.

# AccountNode fields:

  # type: AccountActions
  can { show withdraw deposit }

  # type: AccountData
  data { id name balance }

  # type: AccountRelations
  relations {

    # type: TransactionCollection
    transactions(query:{ sorts:[{ field: "amount", dir: Desc }]}){

      # type: PageInfo
      pageInfo { ...PageInfoFragment }

      # type: TransactionCollectionActions
      can { show }

      # type: GraphQLList(TransactionNode)
      nodes {

        # type: TransactionActions
        can { show }

        # type: TransactionData
        data { id description amount }

        # type: TransactionRelations
        relations { ... }
      }
    }
  }

This is in contrast to the flat equivalent:

# AccountNode fields:

  # authorisation
  canShow

  # authorisation
  canWithdraw

  # authorisation
  canDeposit

  # data
  id

  # data
  name

  # data
  balance

  # relation / connection
  transactionRelation(query:{ sorts:[{ field: "amount", dir: Desc }]}){

    # pagination
    pageInfo { ...pageInfoFragment }

    # list
    nodes {

      # authorisation
      canShow

      # data
      id

      # data
      description

      # data
      amount

      # relation / connection
      accountRelation{ ... }
    }
  }

Code

Schema

As always with GraphQL, we provide a root Query type for reading and root Mutation type for updating.

Due to NodeJS module resolution and the cyclic nature of graph data structures, we run into import races when Node resolves our program. To get around this, the graphql library lets us define fields as Thunks. Instead of defining a field object, we define a function that returns the field object. After all circular modules are resolved by node, the GraphQL server can resolve the fields and the schema.

/**
 * @ root.gql.ts
 *
 * Root Queries & Mutations
 */

import { GraphQLObjectType }  from 'graphql';
import { GqlContext } from './common/gql.context.ts';
import { AccountQuery } from './account/account.gql.query.ts';
import { TransactionQuery } from './transaction/transaction.gql.query.ts';

const RootQuery = new GraphQLObjectType<unknown, GqlContext>({
  name: 'RootQueryType',
  // To keep things consistent and avoid circular dependency issues we write all our `fields` as thunks.
  fields: () => ({
    ...unthunk(AccountQuery),
    ...unthunk(TransactionQuery),
  }),
})

const RootMutation = new GraphQLObjectType<unknown, GqlContext>({
  name: 'RootMutationType',
  fields: () => ({
    ...unthunk(AccountMutation),
    ...unthunk(TransactionMutation),
  }),
})

// give this schema to the Gql server
export const schema = new GraphQLSchema({
  query: RootQuery,
  mutation: RootMutation,
});

function unthunk<T>(mbThunk: Thunk<T>): T {
  if (typeof mbThunk === 'function') return (mbThunk as () => T)();
  return mbThunk;
}

AccountQuery

We define root level query fields for Accounts, which are provided to the RootQuery above.

This is what lets us write

query {
  accounts{
    ...
  }
}

/**
 * @ account/account.gql.query.ts
 *
 * Accounts Query
 *
 * For queries like FindManyAccounts and FindOneAccount
 */

import HttpErrors from 'http-errors';
import { GqlContext } from '../common/classes/gql.context.ts';
import { Thunk, GraphQLFieldConfigMap, GraphQLNonNull } from "graphql";


// root Query type for an account
// is an "Api Endpoint" for querying Accounts
// thunk with the query fields to reduce the change of nasty import races
export const AccountQuery: Thunk<GraphQLFieldConfigMap<unknown, GqlContext>> = () => ({
  /**
   * Find Accounts
   */
  accounts: {
    // tell Gql to resolve the returned object as an AccountCollectionNode
    type: GraphQLNonNull(AccountCollectionNode),

    // Query can have filtering, sorting, pagination (limit, offset), withSoftDeleted, etc...
    args: { query: { type: CollectionQueryInput, }, },

    // return an AccountNodeCollectionSource type, NOT an AccountNode type.
    // Gql will resolve it as an AccountNodeCollection type.
    resolve: async (parent, args, ctx): Promise<IAccountCollectionNodeSource> => {
      if (!ctx.services.accountPolicy.canFindMany()) {
        throw new HttpErrors.Forbidden('Cannot Find Accounts');
      }

      const options = parseQuery(args.query);

      const results  = await ctx
        .services
        .accountRepository
        .findAllAndCount(options);

      // remove models that the requester is unauthorised to view
      // (that should have been filtered out by repository)
      const findableModels: (null | AccountModel)[] = results.rows.map((model) => (
        ctx.services.accountPolicy.canFindOne({ model })
          ? model
          : null
      ));

      const pageInfo = getPageInfo(options, results);

      const collectionSource: IAccountCollectionNodeSource = {
        nodes: findableModels,
        pageInfo,
      };

      return collectionSource;
    },
  },
});

AccountCollectionNode

An AccountCollectionNode represents a paginated list of Accounts.

It has an array of AccountNodes, a AccountCollectionActions object with actions the client is/isn't authorised to take on the collection, and a PageInfo object detailing the results page number, total pages, whether there are more pages, etc...

/**
 * @ account/account.gql.collection.node.ts
 *
 * AccountCollectionNode
 *
 * GraphQLObjectType for a paginated collection of Accounts
 */

import { GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLBoolean } from "graphql";
import { GqlContext } from "../common/classes/gql.context";
import { GqlNone, IGqlNoneSource } from "../common/gql/gql.none";
import { IPageInfoSource, PageInfo } from "../common/gql/gql.page-info";
import { AccountNode, IAccountNodeSource } from "./account.gql.node";
import { AccountModel } from "./account.model";

export interface IAccountCollectionNodeSource {
  nodes: (null | AccountModel)[];
  pageInfo: IPageInfoSource;
  // ...other collection metadata
}
export const AccountCollectionNode = new GraphQLObjectType<IAccountCollectionNodeSource, GqlContext>({
  name: 'AccountCollectionNode',
  fields: () => ({
    // resolve: list of AccountNode
    nodes: {
      type: GraphQLNonNull(GraphQLList(AccountNode)),
      // source as array of AccountModel's
      resolve: (parent): (null | IAccountNodeSource)[] => parent.nodes,
    },

    // resolve: PageInfo
    pageInfo: {
      type: GraphQLNonNull(PageInfo),
      resolve: (parent): IPageInfoSource => parent.pageInfo,
    },

    // resolve: AccountCollectionActions
    can: {
      resolve: (parent): IGqlNoneSource => GqlNone,
      type: GraphQLNonNull(new GraphQLObjectType<IGqlNoneSource, GqlContext>({
        name: 'AccountCollectionActions',
        fields: {
          show: {
            type: GraphQLNonNull(GraphQLBoolean),
            resolve: (parent, args, ctx): boolean => {
              return ctx.services.accountPolicy.canFindMany();
            },
          },
          create: {
            type: GraphQLNonNull(GraphQLBoolean),
            resolve: (parent, args, ctx): boolean => {
              return ctx.services.accountPolicy.canCreate();
            },
          },
        }
      })),
    },
  }),
});

AccountNode

AccountNode is the root node for an Account. Its fields are nodes representing different categories of data of the parent Account such as AccountData with the id, name, etc..., AccountActions with client authorisation, and AccountRelations.

Note that the AccountNode and all its children; AccountData, AccountActions, and AccountRelations, all have the same source/parent, the ORM's AccountModel. Look at the AccountNode's fields to see where we tell GraphQL to resolve as AccountData, AccountActions, AccountRelations, but simply return the parent.

Understanding this is especially crucial for paginated relations since even if you prefer flat over nested schema, paginated Relations/Connections must always be nested.

        Root Node
            |
  Paginated Connection Node - requires the RootNode's source for querying the related data
       /          \
   PageInfo   Related Nodes

i.e.

query {
  rootNode{
    # paginated connection node
    # must provide the root nodes source to the xToManyRelation's resolver
    xToManyRelation{
      pageInfo
      childNodes{ ... }
    }
  }
}

/**
 * @ account/account.gql.node.ts
 * 
 * AccountNode
 * 
 * GrapQLObjectType for an Account
 */

// AccountNode Source is an AccountModel from our ORM
export type IAccountNodeSource = AccountModel;
export const AccountNode = new GraphQLObjectType<IAccountNodeSource, GqlContext>({
  name: 'AccountNode',
  fields: () => ({

    // resolve: AccountData (such as from database `accounts` table)
    data: {
      resolve: (parent): IAccountNodeSource => parent,
      type: GraphQLNonNull(new GraphQLObjectType<IAccountNodeSource, GqlContext>({
        name: 'AccountData',
        fields: {
          id: { type: GraphQLNonNull(GraphQLFloat), resolve: (parent): number => parent.attributes.id, },
          name: { type: GraphQLNonNull(GraphQLString), resolve: (parent): string => parent.attributes.name, },
          balance: { type: GraphQLNonNull(GraphQLFloat), resolve: (parent): number => parent.attributes.balance, },
          owner_id: { type: GraphQLNonNull(GraphQLFloat), resolve: (parent): number => parent.attributes.owner_id, },
          // more fields...
        },
      })),
    },

    // resolve: AccountActions (GATEOAS)
    can: {
      resolve: (parent): IAccountNodeSource => parent,
      type: GraphQLNonNull(new GraphQLObjectType<IAccountNodeSource, GqlContext>({
        name: 'AccountActions',
        fields: () => ({
          show: {
            type: GraphQLNonNull(GraphQLBoolean),
            resolve: (parent, args, ctx): boolean => {
              return ctx.services.accountPolicy.canFindOne({ model: parent });
            },
          },
          withdraw: {
            type: GraphQLNonNull(GraphQLBoolean),
            resolve: (parent, args, ctx): boolean => {
              return ctx.services.accountPolicy.canWithdraw({ model: parent });
            },
          },
          deposit: {
            type: GraphQLNonNull(GraphQLBoolean),
            resolve: (parent, args, ctx): boolean => {
              return ctx.services.accountPolicy.canDeposit({ model: parent });
            },
          },
        }),
      })),
    },

    // resolve: AccountRelations (or AccountConnections)
    relations: {
      resolve: (parent): IAccountNodeSource => parent,
      type: GraphQLNonNull(AccountRelations),
    },
  }),
});

// We've avoided embedding AccountNodeRelations in AccountNode to avoid circular references that TypeScript doesn't like

// Note that this code is mostly generic and could be extracted into a function
// that allows modifying the `where` clause based on different relations (or no relation)
// that have a BelongsTo/BelongsToMany (one|many-x-to-many-Transactions) relation with Transactions
const AccountRelations: GraphQLObjectType<IAccountNodeSource, GqlContext> = new GraphQLObjectType<IAccountNodeSource, GqlContext>({
  name: 'AccountRelations',
  fields: () => ({
    transactions: {
      // tell Gql to resolve the returned object as an TransactionCollectionNode
      type: GraphQLNonNull(TransactionCollectionNode),

      args: { query: { type: CollectionQueryInput, }, },

      // Resolve to the TransactionNodeSource type
      resolve: async (parent, args, ctx): Promise<ITransactionCollectionNodeSource> => {
        // parse the Gql Query Input into repository options
        const options = parseQuery(args.query);

        const results  = await ctx
          .services
          .transactionRepository
          .findAllAndCount({
            ...options,
            filters: {
              ...options.filters,
              // transactions that belong to the account
              account_id: parent.attributes.id,
            },
          });

        // remove models that the requester is unauthorised to view
        // and that weren't caught by the dynamic filter scope in the repository
        const findableModels: (null | TransactionModel)[] = await Promise.all(results
          .rows
          .map(async (model) => {
            return ctx
              .services
              .transactionPolicy.canFindOne({ model, account: parent })
                ? model
                : null
          })
        );

        // paginated collection nodes have pageInfo describing the results...
        const pageInfo = getPageInfo(options, results);

        // resolve (return) to the source required for a TransactionCollectionNode
        const collectionSource: ITransactionCollectionNodeSource = {
          nodes: findableModels,
          pageInfo,
        };

        return collectionSource;
      },
    },
  }),
})

AccountPolicy

Policy classes are not specific to GraphQL but are included here because of their importance. They are single responsibility objects that authorise actions. This means they can both be used to 403/404 a request, or to provide a G|HATEOAS response publishing authorised actions. They can be used in HTTP Requests, GraphQL requests, WebSocket requests, RPC requests, CRON contexts, Job contexts, Migration contexts, Seeder contexts, or anything else that could fit a RequestContext interface.

/**
 * @ account/account.policy.ts
 * 
 * AccountPolicy
 * 
 * Handles authorisation for Accounts
 */
export class AccountPolicy {
  constructor(
    protected readonly ctx: BaseContext,
  ) {
    //
  }

  /**
   * Can the Requester Find Accounts?
   */
  canFindMany(): boolean {
    return this.ctx.hasPermission(Permission.Account.ViewOwn);
  }

  /**
   * Can the Requester Create an Account?
   */
  canCreate(): boolean {
    return this.ctx.hasPermission(Permission.Account.Create);
  }

  /**
   * Can the Requester Find the Account?
   *
   * @param arg
   */
  canFindOne(arg: { model: AccountModel }): boolean {
    const { model } = arg;

    // must be Owned by the Requester
    if (!model.isOwnedBy(this.ctx)) return false;

    return this.ctx.hasPermission(Permission.Account.ViewOwn);
  }

  /**
   * Can the Requester Withdraw from the Account?
   *
   * @param arg
   */
  canWithdraw(arg: { model: AccountModel }): boolean {
    const { model } = arg;

    // must be Findable
    if (!this.canFindOne({ model })) return false;

    // must be Owned by the Requester
    if (!model.isOwnedBy(this.ctx)) return false;

    return this.ctx.hasPermission(Permission.Account.WithdrawOwn);
  }

  /**
   * Can the Requester Deposit to the Account?
   *
   * @param arg
   */
  canDeposit(arg: { model: AccountModel }): boolean {
    const { model } = arg;

    // must be Findable
    if (!this.canFindOne({ model })) return false;

    // must be Owned by the Requester
    if (!model.isOwnedBy(this.ctx)) return false;

    return this.ctx.hasPermission(Permission.Account.DepositOwn);
  }
}

Policies exist in contrast to other popular techniques like Guards that apply method/route based authorisation to endpoints (such as resolvers, HTTP endpoints, etc...) and whose logic can't be shared with different parts of the codebase. Guards' power is they're simple and readable. Guards are useful when working at high resolution such as authorising access to sensitive fields like date_of_birth or email, where the authorisation is too granular to publish in practice.

A guard example adopted from TypeGraphQL.

// Guard example from TypeGraphQL, using the @Authorized decorator

@Resolver()
class MyResolver {
  // Since the logic is statically attached to the endpoint and inaccessable elsewhere in the
  // application, we can't publish this authorisation to the client without duplicating the logic
  // (i.e. const canDoThing = user.permissions.includes("ADMIN")...)
  @Authorized("ADMIN")
  @Query()
  authedQuery(): string {
    return "Admin users only!";
  }

}

The rest...

For the remaining server code see the GitHub repository for this post.

What we didn't cover

Using DataLoader to solve the n+1 problem
Using a database:
- ORM
- Migrations
- Seeing
- Transactions
- ...
How to serve a GraphQL server over HTTP (view the Source Code for an example)

Hosting this example server:

With Docker:

docker run \
  --name graphql_typescript_server \
  -p 5000:5000 \
  -e PORT=5000 \
  -e LOG_DIR=./storage/logs \
  -e LOG_MAX_SIZE=20m \
  -e LOG_ROTATION_MAX_AGE=7d \
  -e RATE_LIMIT_WINDOW_MS=60000 \
  -e RATE_LIMIT_MAX=100 \
  --rm \
  nick3141/graphql-typescript-server:latest

With Docker Compose:

version: "3"

services:
  graphql_typescript_server:
    container_name: graphql_typescript_server
    image: nick3141/graphql-typescript-server:latest
    restart: unless-stopped
    ports:
      - 5000:5000
    environment:
      - PORT=5000
      # optional:
      # - LOG_DIR=./storage/logs
      # - LOG_MAX_SIZE=20m
      # - LOG_ROTATION_MAX_AGE=7d
      # - RATE_LIMIT_WINDOW_MS=60000
      # - RATE_LIMIT_MAX=100
    volumes:
      - ./_v_logs:/usr/src/app/storage/logs

DEV Community: Nick Kelly

JavaScript Inheritance: The Dark Arts

How many can you get right?

1. Overriding getters and setters

2. Deleting from a class instance

3. Deleting from an object

4. Overriding constructors???

Inheritance

Enter: [[Prototype]]

Functions

Enter: Constructors

ES2015 classes without ES2015 syntax

The super Problem

Pre ES2015 classes by example

Access to inherited properties

Who cares?

How does TypeScript fit into this?

Revisiting our examples

Explanation: 1. Overriding getters and setters

Explanation: 2. Deleting from a class instance

Explanation: 3. Deleting from an object

Explanation: 4. Overriding constructors???

UPDATE 2021-08-11

Further Reading

Writing a GraphQL TypeScript Server for NodeJS

Writing a GraphQL TypeScript Server for NodeJS

This is for

This is not

Final result:

GraphiQL

Partial Schema

Supported queries

Background

Code-first: decorators vs objects

GraphQL as the Engine of Application State

Leveraging Query Resolution to Create Flexible Graphs

Code

Schema

AccountQuery

AccountCollectionNode

AccountNode

AccountPolicy

The rest...

What we didn't cover

Hosting this example server:

With Docker:

With Docker Compose:

The `super` Problem