Skip to content
app-compose

compose.up

compose.up is the primary function used to initialize list of containers, ensuring they are set up in the correct order based on their dependencies. This function manages the execution flow and provides optional debugging output.

Syntax

type Config = {
  apis?: boolean;
  debug?: boolean;
  autoResolveDeps?: {
    strict: true;
    optional?: boolean;
  };
  onFail?: (_: { id: AnyContainer['id']; error: Error }) => unknown
};


compose.up(containers: Container[], config?: Config): Promise<{
  hasErrors: boolean;
  statuses: Record<Container['id'], Container['status']>;
}>

Parameters

  • containers (Container[]): An array of containers to initialize. Each container in the array is processed based on its dependencies (dependsOn and optionalDependsOn), regardless of the order in which it appears.
  • config (optional, { debug?: boolean, apis?: boolean, autoResolveDeps?: { strict: true, optional?: boolean } }): An optional configuration object with the following properties:
    • debug (boolean): If true, compose.up will output detailed status updates to the console each time a container’s status changes. This is useful for tracking initialization and troubleshooting dependency issues.
    • apis (boolean): If set to true, the returned result from compose.up will include an apis object. In this object, each key is the id of a container, and the corresponding value is the api from the container’s start function. The keys in apis are always optional because, at the type level, we cannot determine if a container has transitioned to the done status.
    • autoResolveDeps ({ strict: true, optional?: boolean }): Allows automatic resolution of dependencies. If strict is set to true, all strict dependencies are resolved automatically. The optional property, if set to true, enables automatic resolution of optional dependencies as well, eliminating the need to manually pass them to compose.up.
    • onFail (function): An optional callback that is called when a container transitions to the fail state. Receives an object with the container’s id and the error that caused the failure. This is useful for logging, error tracking, or triggering recovery mechanisms.

Return Value

compose.up returns a promise that resolves to an object with the following structure:

  • hasErrors (boolean): Indicates whether any container encountered an error during initialization.
  • statuses (Record<Container['id'], Container['status']>): An object that maps each container ID to its final status (idle, pending, done, fail, or off).
  • apis (Record<Container['id'], Container['api']>): If compose.up.config set to true

Example

import { createContainer, compose } from '@grlt-hub/app-compose';


const userContainer = createContainer({
  id: 'user',
  start: async () => {
    return { api: { userId: 'user123' } };
  },
});


const settingsContainer = createContainer({
  id: 'settings',
  dependsOn: [userContainer],
  start: () => {
    return { api: { theme: 'dark' } };
  },
});


await compose.up([userContainer, settingsContainer], { debug: true });

Expected Resolution Order

Terminal window
userContainer: idle
settingsContainer: idle
###
userContainer: pending
settingsContainer: idle
###
userContainer: done
settingsContainer: pending
###
userContainer: done
settingsContainer: done

How autoResolveDeps Works

When autoResolveDeps is used, compose.up will automatically identify and include all necessary dependencies for each container. This feature is particularly useful when dealing with complex dependency graphs where manually listing all containers is error-prone and difficult to manage.