GitHub - andrewhathaway/manifest-pattern: The Manifest Pattern helps engineers build type-safe dynamic user interfaces and applications without having implementation-specific code littered throughout your codebase.

The Manifest Pattern helps engineers build type-safe dynamic user interfaces and applications without having implementation-specific code littered throughout your codebase. The Manifest Pattern encourages implementation code to be co-located to improve development experience and confidence when implementing new functionality. Your builds will fail unless new functionality is fully implemented.

The Manifest Pattern pairs well with a discriminated union, and can be used to build dynamic forms, dashboard widget systems, complex logic builders, and more.

This repository contains tool(s) to help get you started using the manifest pattern, but they are entirely optional. The package has no dependencies.

You can read more about the Manifest Pattern on my blog.

Installation

npm install manifest-pattern

Usage

Step 1) Create the Manifest Type

Manifests are built around a union type, much like a discriminated union. Your Manifest interface can encapsulate all the functionality your application needs, including defining values, functions, and UI components for each unique implementation.

You can extend your Manifest interface over time and implement the changes across every Manifest-implementation to ensure your application will function correctly, and your build is successful.

import type { Manifest } from 'manifest-pattern';

type ValueType = 'number' | 'string';

interface ValueTypeManifest<T extends ValueType = ValueType> extends Manifest<T> {
  listName: string; // Specific to an application
  shouldAllowSelection(): boolean; // Specific to an application
  isValid(val: unknown): boolean; // Specific to an application
  viewComponent: React.ComponentType<ViewComponentProps> | null; // Specific to an application
}

Step 2) Create Manifest Instances

Create classes or objects that implement your Manifest type for each of the union values.

const numberManifest: ValueTypeManifest<'number'> = {
  type: 'number',
  listName: 'Number',
  shouldAllowSelection: () => true,
  isValid: x => typeof x === 'number',
  viewComponent: null
};
const stringManifest: ValueTypeManifest<'string'> = {
  type: 'string',
  listName: 'String',
  shouldAllowSelection: () => true,
  isValid: x => typeof x === 'string',
  viewComponent: null
};

Step 3) Build the Manifest Registry

Create a registry and add the instances, or use the helper provided.

import { ManifestRegistry, createManifestRegistry } from 'manifest-pattern';

// Option 1: Add-when needed/ready
const valueTypeManifestRegistry = new ManifestRegistry<ValueTypeManifest>()
  .addManifest(numberManifest)
  .addManifest(stringManifest);

// Option 2: Add-all upfront
const valueTypeManifestRegistry = createManifestRegistry<ValueTypeManifest>({
  number: numberManifest,
  string: stringManifest
});

You'll need a way to get access to the registry throughout your codebase, such as an in-memory cache, context, or file import.

Step 4) Use the Manifest Registry

`getManifests`

Get all Manifest instances added to the registry. Useful when allowing users to select an option from a list, rendering dynamic content, and more.

type SelectOption = {
  id: ValueType;
  label: string;
};

const selectOptions = valueTypeManifestRegistry
  .getManifests()
  .filter(m => m.shouldAllowSelection())
  .map(
    (m): SelectOption => ({
      id: m.type,
      label: m.listName
    })
  );

`getManifestOrNull`

Get a specific instance of a manifest by type, or return null. This method is the most-used and allows code to remain ignorant of specific implementation details.

Dynamic React Component Rendering Example:

const ViewComponent = valueTypeManifestRegistry.getManifestOrNull('number')?.viewComponent ?? null;
if (ViewComponent === null) {
  return <div>Something went wrong.</div>;
}

return <ViewComponent />;

Dynamic Function Usage Example:

const formValidator = (formValues): string | null => {
  const manifest = valueTypeManifestRegistry.getManifestOrNull(formValues.selectedValueType);
  if (manifest === null) {
    return 'Invalid Value Type Selected';
  }

  return !manifest.isValid(formValues.value) ? 'Value Entered is Invalid' : null;
};

`getManifestOrThrow`

Similar to the above but instead throws an Error when a manifest is not found for the type given.

const formValidator = (formValues): string | null => {
  try {
    const manifest = valueTypeManifestRegistry.getManifestOrNull(formValues.selectedValueType);

    return !manifest.isValid(formValues.value) ? 'Value Entered is Invalid' : null;
  } catch (err) {
    return 'Invalid Value Type Selected';
  }
};