dlayer v0.2.2

dlayer

This library (and its documentation) is still a work-in-progress!

dlayer is a GraphQL-like data access layer. It lets you combine data from multiple sources into a single coherent API - and it's designed for application-internal use first and foremost, with network accessibility being an optional add-on.

dlayer differs from GraphQL in a number of important ways:

• dlayer supports recursive queries without needing schema hacks; both bounded and unbounded.
• dlayer is modular by default; a dlayer API can be composed of many independent 'modules' that can reference and extend each other when available. This allows for eg. constructing plugin systems, like in sysquery, as well as making it easier to loosely couple your API definition.
• dlayer does not use a separate schema; the schema is implicitly defined by what the API returns. This essentially makes it dynamically typed; however, trying to access a non-existent property of the schema is an error.

Module format

A module is an object of the following shape:

{
	name: "a unique name/identifier for the module",
	makeContext: function() {
		// A function that returns a fresh set of context values (called once per query)
		return {
			// This can contain simple values, but also initialized functions,
			// database instances, whatever stateful thing your type implementations need.
			// Whatever you specify here will *only* be available in the context from
			// within the methods that are defined in this module, not in other modules!
		};
	},
	types: {
		"your-app.type-name": function(args) {
			// NOTE: No context is available here; this function is just meant to construct
			// a new object 'shape', not to do any business logic
			return {
				someStaticProperty: "foo",
				someDynamicProperty: async function(propertyArgs, context) {
					// Do some dynamic logic here, potentially using stuff from the context
					return whatever;
				}
			};
		}
	},
	extensions: {
		"your-app.type-from-another-module": {
			extendedProperty: async function(propertyArgs, context) {
				// Some dynamic logic, same as a normal type function, except this module
				// doesn't need to "own" that type to attach its own properties to it.
				return whatever;
			}
		}
	},
	root: {
		some: {
			nested: {
				path: async function(args) {
					// Again, some dynamic logic, maybe we want to create some instance of
					// our custom type here?
					return $make("your-app.type-name", {});
				}
			}
		}
	}
}

Properties of the context

• async $getProperty(object, propertyName): internally resolve and return the specified property on the specified object (use this as a reference to the object that the method is defined on)
• async $getPropertyPath(object, propertyPath): like $getProperty, but accepts a property path (period-delimited string or array of path component strings)
• async $make(typeName, arguments): creates a new instance of the specified type
• async $maybeMake(typeName, arguments): like $make, but silently returns undefined if the type doesn't exist; typically used for optional schema add-ons
• $getModuleContext(moduleName): you should not need this in normal usage! This is an escape hatch to access the context of a module by that module's name; it's typically only necessary when eg. developing utilities for dlayer that provide queries separately for the user to place somewhere in their schema, as those queries will technically execute outside of any module

Aside from these utility functions, the context will also contain all the properties that were returned from your makeContext methods.