Helper methods

defineDmnoService

defineDmnoService({ opts })

See the service config in the schema guide for more information.

This method is used to define the configuration schema in each of your services, including the root. It takes an object as an argument with the following properties:

Schema

type DmnoServiceConfig = {
  isRoot?: boolean,
  name?: string,
  settings?: {
    dynamicConfig: DynamicConfigModes,
  },
  schema: Record<string, ConfigItemDefinitionOrShorthand>,
  // rest of props only available when isRoot !== true
  parent?: string,
  tags?: string[],
  pick?: Array<PickConfigItemDefinition | string>,

};

Properties

Name	Type	Required	Description
isRoot	boolean	No	MUST be set to true for root service only.
name	string	No	The name of the workspace.
parent	string	No	The name of the parent service.
tags	string[]	No	An array of tags for the service.
settings	{ dynamicConfig: DynamicConfigModes }	No	Settings to apply to the service and as defaults for any children
pick	Array<PickConfigItemDefinition | string>	No	An array of items to pick from the parent or other service(s). This can be a string (the key) or a PickItemDefinition object.
schema	Record<string, ConfigItemDefinitionOrShorthand>	Yes	The schema for the workspace. These are the configuration items that will be available to all services.

Note that when isRoot is true, some of the options are not available:

• parent is the name of the parent service.
• tags is an array of tags for the service.
• pick is an array of items to pick from the parent or other services. This can be a string (the key) or a PickConfigItemDefinition object.

PickItemDefinition

The PickItemDefinition type is an object with the following properties:

type PickConfigItemDefinition = {
  /** which service to pick from, defaults to "root" */
  source?: string;
  /** key(s) to pick, or function that matches against all keys from source */
  key: string | Array<string> | ((key: string) => boolean),
  /** new key name or function to rename key(s) */
  renameKey?: string | ((key: string) => string),
  /** function to transform value(s) */
  transformValue?: (value: any) => any,
};

Example:

import { defineDmnoService, DmnoBaseTypes } from 'dmno';

export default defineDmnoService({
  name: 'MyConfig',
  parent: 'root',
  pick: [
    {
      key: 'ITEM0',
    },
    {
      key: 'ITEM1',
      renameKey: 'NEW_ITEM1',
    },
    {
      key: 'ITEM2',
      transformValue: (value) => `${value} transformed`,
    },
  ],
  schema: {
    MYFIELD: DmnoBaseTypes.string({
      required: true,
    }),
    MYFIELD2: DmnoBaseTypes.number({
      required: true,
    }),
    MYFIELD3: DmnoBaseTypes.boolean({
      required: true,
    }),
  },
});

DynamicConfigModes

The DynamicConfigModes type has the following values:

type DynamicConfigModes =
/* non-sensitive = static, sensitive = dynamic (this is the default) */
  'public_static' |
  /* everything static, dynamic not supported */
  'only_static' |
  /* everything dynamic, static not supported */
  'only_dynamic' |
  /* default is static */
  'default_static' |
  /* default_dynamic */
  'default_dynamic';

Tip

For more on dynamic config modes, see the Dynamic vs static config guide.

ConfigItemDefinition

The ConfigItemDefinition type is an object with the following properties:

Schema

type ConfigItemDefinition = {
  asyncValidate?: function(),
  coerce?: function(),
  description?: string,
  dynamic?: boolean,
  exampleValue?: any,
  expose?: boolean,
  extends?: DmnoDataType | string | () => DmnoDataType,
  externalDocs?: { description?, url } | Array<{ description?, url }>,
  required?: boolean,
  sensitive?: boolean,
  summary?: string,
  typeDescription?: string,
  ui?: { color, icon },
  useAt?: 'build' | 'boot' | 'run' | 'deploy' ,
  validate?: function(),
  value?: InlineValueResolverDef
  }

Properties

Name	Type	Required	Description
asyncValidate	function	No	An async function to validate the value.
coerce	function	No	A function to coerce the value.
description	string	No	A description of the item.
dynamic	boolean	No	Whether the item is dynamic.
exampleValue	any	No	An example value for the item.
expose	boolean	No	Whether the item should be exposed to other services. i.e., is it "pickable" by siblings
extends	DmnoDataType | string | () => DmnoDataType	No	A string (the name of the type), an initialized dmno data type, or a function that returns a DmnoDataType
externalDocs	{ description?, url } | Array<{ description?, url }>	No	External documentation for the item.
required	boolean	No	Whether the item is required.
sensitive	boolean	No	Whether the item is sensitive.
summary	string	No	A short summary description of the item.
typeDescription	string	No	A description of the type.
ui	{ color, icon }	No	UI settings for the item. COMING SOON
useAt	ConfigRequiredAtTypes	No	When the item is required.
validate	function	No	A function to validate the value.
value	InlineValueResolverDef	No	A static value, a function that returns a static value, or a "resolver" like a plugin helper function that fetches a value.

Examples illustrating implicit and explicit type extensions:

import { defineDmnoService, DmnoBaseTypes } from 'dmno';

export default defineDmnoService({
  schema: {
    ITEM0: {}, // defaults to string
    ITEM1: 'string',
    ITEM2: DmnoBaseTypes.string,
    ITEM3: DmnoBaseTypes.string(),
    ITEM4: {
      extends: 'string',
    },
    ITEM5: {
      extends: DmnoBaseTypes.string,
    },
    ITEM6: {
      extends: DmnoBaseTypes.string({}),
    },
  },
});

Did you know?

All of the above examples are equivalent.

createDmnoDataType

createDmnoDataType({ opts })

This method is used to create a new data type. It takes an object as an argument with the following properties:

type DataTypeOpts = {
  name: string;
  extends: string | DmnoDataType | (() => DmnoDataType);
  settingsSchema?: Record<string, unknown>;
  validate?: (ctx, settings) => boolean;
  coerce?: (ctx, settings) => unknown;
};

Example:

const myType = createDmnoDataType({
  name: 'MyType',
  extends: DmnoBaseTypes.string({
    // string specific settings object
  }),
  settingsSchema: {
    // user type specific settings object
  },
  validate: (value) => {
    // return true if value is valid
    // has access to settingsSchema
  },
  coerce: (value) => {
    // return coerced value
    // has access to settingsSchema
  },
});

You can then use it in your config schema like so:

const myType = DmnoBaseTypes.MyType({ settings });

export default defineDmnoService({
  name: 'MyConfig',
  parent: 'root',
  schema: {
    MYFIELD: {
      extends: myType,
      required: true,
    },
    MYFIELD2,
    MYFIELD3,
  },
});

switchBy

switchBy('SWITCH_BY_KEY': string, { branches })

This method is used to define different configurations for different values of a particular config item. Its arguments are a string (i.e., the key name) and an object with the following properties:

type branches = {
  _default?: any;
  [key: string]: any;
};

Note: _default is a reserved key to represent the default branch. This default will be selected if the current value of the switch is not found on any other branch. All the other keys should match the possible values of the SWITCH_BY_KEY config item.

A real example using an enviroment flag:

import { switchBy } from 'dmno';

export default defineDmnoService({
  schema: {
    APP_ENV: {
      value: 'development',
    },
    MY_CONFIG_ITEM: {
      value: switchBy('APP_ENV', {
        _default: 'dev/default value', // <- matches
        test: 'test value',
        staging: 'staging value',
        production: 'prod value',
      }),
    },
  },
});

Default branch is optional

Having a _default branch is not required, but if there is no default branch and an unknown value is passed to the switch, you will get a ResolutionError. If this is not what you want, you must add _default: undefined or add branches for all expected switch values, even if they are set to resolve to undefined.

Switching based on environment

While switching based on an environment flag (e.g., dev/staging/prod) is the most common use case for branching logic in your config, we do not recommend using NODE_ENV as that flag for most projects. See our Multiple Environments guide for more details.