@openstax/ts-utils

A collection of utilities typescript applications. browser and server support.

Libraries

overviews of the libraries provided and their purposes, for more specific information check out the comments in the source code.

types.ts

utility types, no javascript functionality in here. A dumping ground for commonly used utility types or sorcery copied of stack overflow.

guards.ts

generic type guards. most of this isn't super interesting its just annoying to have to re-define these in every project.

assertions.ts

like a guard but throws if the condition fails. you can use an assertion if you're extra sure that something is true but typescript isn't so sure, its possible that a bug might exist but normally your expected case should always be the case. these assertions allow you to have useful errors/messages for the exceptional bug, without generating conditional logic in your application code. this is almost entirely driven by not wanting to create code branches that will then need unit tests.

index.ts

basic array/object access/manipulation utilities

errors.ts

a set of common application errors for the other libraries to use

fetch.ts

utilities for working with fetch and fetching data. mostly there are constructors and guards for working with response objects that capture both a request status and associated data. the actual fetch api only throws if there is a connection errors, so most data access utilities need a way to communicate application layer failures back to the client in a discernible way. you can almost do this with regular response objects, but then you're forcing all of the response processing down into user-land, and this system provides an additional loading state for UIs.

config.ts

defines ConfigProvider as an arbitrarily nested object where leaves must be ConfigValueProviders. ConfigValueProviders are strings, promises of strings, functions without arguments that return strings, or promises of strings. the library has a utility to resolve a ConfigValueProvider to a string, and a few re-usable providers.

middleware.ts

middleware are chains of functions, with shared access to a parent application or services, that modify or decorate a result. middleware chains are used to pre-process requests before they reach routing, post-process results after routing, and compose service providers for the routes to use.

routing.ts

a flexible routing library with utils for defining routes, matching requests to routes, and rendering urls for routes. strong typing for route params, request bodies, response bodies. reverse routing asserts not only that the correct route and params are given, but that the route is composed in the application. built to be implementation agnostic and support both browser SPA routing and server side API routing.

pagination.ts

utilities for interpreting pagination requests and generating pagination responses for both 'load more' and 'page number' style pagination. included middleware for working with the routing library.

Services

Services differ from the rest of the libraries in that they have a single discrete interface and support multiple implementations of that interface.

apiGateway

dynamically generates an api client from route configuration. if you're using the routing library in the api, this allows you to import your route types directly into your client and have very strong typing on your api calls for free. includes error handling, filtering responses by status code, and narrowing the expected data type by given status code.

authProvider

integrates with openstax.org/accounts, includes several implementations for both browser and server side integrations.

lrsGateway

handles authentication and payload formatting for interacting with the LRS

versionedDocumentStore

a key/value document store with integrated audit logging. all writes are done as new versions of documents and version history can be fetched. includes implementations for dynamodb and local file system.

searchProvider

allows filtering and open text search for documents. has strong typing for filterable values based on the document type definition. interface is based on elasticsearch options, but currently we only have an in memory filtering implementation. works out of the box with versionedDocumentStore.

Notes

Service drivers and configuration

Service providers are defined in a little bit of a weird nested way, this is supposed to help separate driver specific and instance specific configurations, and let you swap drivers in different application entry points without too many application dependencies.

an entry point is the file you point to when you build or run the application. the idea is that you make a different entry point files for different environments or contexts. so you have one for launching local development and one for launching an all-in-one stack on a testing server and another one for launching a production environment. in order to reduce environment specific issues you reduce your entry point to be as small as possible and just assemble the required bits for that environment to work. in the recommended setup, one of the main things the entry point does is choose which service provider drivers to use. there are two main benefits of using entry points, its more declarative than using downstream conditional logic with some kind of driver: fs flag in the config, and it allows bundled javascript to only include the dependencies relevant for the drivers that are being used in that build.

the idea is that you may have some entities you're putting in a VersionedDocumentStore and maybe some others in a RelationalEntityStore but you're for sure not putting some versioned entities in dynamo and some in a local json file. so in your development environment entry point you provide your config for versionedDocumentStore: fileSystemVersionedDocumentStore and in the deployed environment entry point you put versionedDocumentStore: dynamoVersionedDocumentStore.

there are two levels the drivers are configured at, one is the driver level and the other is the instance level. for the VersionedDocumentStore the fileSystem driver takes a path to the directory to store the files in. the instance level may vary based on the usage of that driver, for example if you're storing 4 different entities in VersionedDocumentStores, you need to provide different table names to the driver to configure each store to create separate instances of that store. it just happens that for VersionedDocumentStore the fileSystem and dynamo implementations use the same instance config, this isn't always the case. once you get into your application logic you won't know which entry point was used to bootstrap your application, so you'll just know the driver is one of the possible versions, typescript will recognize this and throw an error unless you provide a config that would work for any of the possible drivers. in order to make this more legible (and separate key collisions), most of the services can be set up in the entry point with a config prefix, so when you get into application-land it looks more like you're providing two discrete configs.

for example:

// entry/anEntryPoint.ts
export const lambdaServices = {
  // in this entry we provide the dynamo driver
  versionedDocumentStore: dynamoVersionedDocumentStore({configSpace: 'dynamodb'}),
};

// entry/anotherEntryPoint.ts
export const localServices = {
  // in this entry we provide the fileSystem driver, it has a different config prefix
  versionedDocumentStore: fileSystemVersionedDocumentStore({dataDir, configSpace: 'fileSystem'}),
};

// core/types.ts

// there is other wiring up that happens with the app services on the request responder, if
// you made a new entrypoint and tried to use a different format of services without registering it
// here it would yell at you.
export type AppServices = LambdaServices | LocalServices;

// myCoolDocumentStoreMiddleware.ts

// this config satisfies both config drivers with separate sections for each one.
// the envConfig is defined here, but it wouldn't try to actually resolve that value
// unless it was being used.
const config = {
  fileSystem: {
    tableName: 'coolDocument'
  },
  dynamodb: {
    tableName: envConfig('TestDocumentTableName', 'runtime'),
  }
};

export const myCoolDocumentStoreMiddleware = <M extends {}>(app: AppServices) => {
  // providing the document interface and the config prepares the driver to work for this entity in particular.
  // the extra function call in this line is to work around some typescript quirkiness with generic type inference.
  // this line is only run once when the app is wired up, doing this call here allows the driver to do internal memory caching
  // if it wants to.
  const makeCoolDocumentStore = app.versionedDocumentStore<CoolDocument>()(config);

  return (middleware: M) => ({
    ...middleware,
    // this part is run for every api request processed. in this case there it could have been combined with the call above,
    // but most of the time you'll want to pull in the authProvider and hook up automatic audit logging, and that will be different on 
    // each request. look at the VersionedDocumentStore documentation for details.
    coolDocumentStore: makeCoolDocumentStore('id'),
  })
};