zcb 0.0.6 → 0.0.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 dylanaubrey
+Copyright (c) 2023 Dylan Aubrey
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,364 @@
-# zod-config-builder
+# zcb
 
 Build configs with type safety from zod schema.
 
-[![npm version](https://badge.fury.io/js/%40zod-config-builder.svg)](https://badge.fury.io/js/%40zod-config-builder)
+[![npm version](https://badge.fury.io/js/zcb.svg)](https://badge.fury.io/js/zcb)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**WORK IN PROGRESS**
+Define a configuration schema with [`zod`](https://github.com/colinhacks/zod) and use the output of that in `zcb` to create a config builder with autocomplete and setter value autocomplete.
+
+Use our cli module to build and/or watch a config builder file and transform it into a literally typed config object.
+
+Import that literally typed config in your components along with `zcb` and create a config reader with scoping abilities, config path autocomplete and return value preview.
+
+## Installation
+
+```sh
+npm install zcb
+```
+
+## Usage
+
+* [Create schema](#create-schema)
+* [Create config builder](#create-config-builder)
+* [Transform config builder](#transform-config-builder)
+* [Create config reader](#create-config-reader)
+* [Use config reader](#use-config-reader)
+
+### Create schema
+
+Create the schema for your configuration like in the example below.
+
+```ts
+// ./schema.ts
+import { z } from 'zod';
+import {
+  countryCodes,
+  countryNames,
+  distanceUnits,
+  languageCodes,
+  timezones,
+} from 'zcb';
+
+export const baseSectionSchema = z.object({
+  name: z.string(),
+});
+
+export type SectionType = z.infer<typeof baseSectionSchema> & {
+  sections?: SectionType[];
+};
+
+export const sectionSchema: z.ZodType<SectionType> = baseSectionSchema.extend({
+  sections: z.lazy(() => sectionSchema.array()).optional(),
+});
+
+export const pageSchema = z.object({
+  name: z.string(),
+  path: z.string().optional(),
+  queryParams: z.array(z.string()).optional(),
+  sections: z.array(sectionSchema).optional(),
+});
+
+export type PageType = z.infer<typeof pageSchema>;
+
+const baseRouteSchema = z.object({
+  aliases: z.array(z.string()).optional(),
+  page: z.string(),
+  path: z.string(),
+});
+
+export type RouteType = z.infer<typeof baseRouteSchema> & {
+  routes?: RouteType[];
+};
+
+export const routeSchema: z.ZodType<RouteType> = baseRouteSchema.extend({
+  routes: z.lazy(() => routeSchema.array()).optional(),
+});
+
+export const configSchema = z.object({
+  countryCode: z.enum(countryCodes).optional(),
+  countryName: z.enum(countryNames).optional(),
+  distanceUnit: z.enum(distanceUnits).optional(),
+  languageCodes: z.array(z.enum(languageCodes)).optional(),
+  locales: z.array(z.string().regex(/[a-z]{2}_[A-Z]{2}/)).optional(),
+  name: z.string().optional(),
+  pages: z.record(pageSchema).optional(),
+  routes: z.array(routeSchema).optional(),
+  timeouts: z.record(z.number()).optional(),
+  timezone: z.enum(timezones).optional(),
+});
+
+export type ConfigType = z.infer<typeof configSchema>;
+```
+
+### Create config builder
+
+Then use the schema and its types to create a config builder and build out your configuration like in the example below. The config builder comes with method autocompletion and value type validation. It is important to default export the config builder as this is what the cli build/watch scripts are expecting when they import the config builder.
+
+```ts
+// ./configBuilder.ts
+import kebabCase from 'lodash/kebabCase.js';
+import { createConfigBuilder } from 'zcb';
+import {
+  type ConfigType,
+  type PageType,
+  type RouteType,
+  type SectionType,
+  configSchema,
+  pageSchema,
+  routeSchema,
+  sectionSchema,
+} from './schema.ts';
+
+const configBuilder = createConfigBuilder<ConfigType>(configSchema);
+const routeBuilder = createConfigBuilder<RouteType>(routeSchema, { path: ({ page }) => kebabCase(page) });
+const pageBuilder = createConfigBuilder<PageType>(pageSchema);
+const sectionBuilder = createConfigBuilder<SectionType>(sectionSchema);
+const subsectionBuilder = sectionBuilder.fork();
+
+configBuilder
+  .countryCode('GB')
+  .countryName('United Kingdom')
+  .distanceUnit('km')
+  .languageCodes(['en'])
+  .locales(({ countryCode, languageCodes }) =>
+    languageCodes?.length && countryCode ? languageCodes.map(code => `${code}_${countryCode}`) : []
+  )
+  .name('alpha')
+  .pages({
+    contactDetails: pageBuilder
+      .name('contactDetails')
+      .sections([
+        sectionBuilder.name('header').flush(),
+        sectionBuilder
+          .name('body')
+          .sections([subsectionBuilder.name('main').flush(), subsectionBuilder.name('sidebar').flush()])
+          .flush(),
+        sectionBuilder.name('footer').flush(),
+      ])
+      .flush(),
+    personalDetails: pageBuilder
+      .name('personalDetails')
+      .sections([
+        sectionBuilder.name('header').flush(),
+        sectionBuilder
+          .name('body')
+          .sections([subsectionBuilder.name('main').flush(), subsectionBuilder.name('sidebar').flush()])
+          .flush(),
+        sectionBuilder.name('footer').flush(),
+      ])
+      .flush(),
+  })
+  .routes([routeBuilder.page('personalDetails').flush(), routeBuilder.page('contactDetails').flush()])
+  .timeouts({ apollo: 10_000 })
+  .timezone('Europe/London');
+
+export default configBuilder;
+```
+
+#### builder API
+
+**disable: `() => ConfigBuilder`**
+
+Use to disable a slice of config. Disabled slices are removed from the config when the config builder is transformed into a literally typed object in the cli build/watch step.
+
+**errors: `() => ZodIssue[]`**
+
+Use to validate the config against the schema and return any errors. The primary use for this is internal within the cli build/watch step.
+
+**experiment: `() => ConfigBuilder`**
+
+Use to assign an experiment ID to a slice of config. If an experiment callback file is provided to the cli build/watch step, this ID is used as a marker for where to inject experiment configuration.
+
+**extend: `(value: ConfigBuilder) => void`**
+
+Use to extend an existing config builder.
+
+**flush: `() => JsonObject`**
+
+Use to flush the values from a config builder so that it can be immediately reused.
+
+**fork: `() => ConfigBuilder`**
+
+Create a clone of a config builder. Useful if you need to use the same config builder within itself.
+
+**toJson: `() => string`**
+
+Returns the config values as a pretty-printed JSON string.
+
+**validate: `() => boolean`**
+
+Use to validate the config against the schema and return true/false. The primary use for this is internal within the cli build/watch step.
+
+**values: `() => JsonObject`**
+
+Use to return the config values as an object.
+
+---
+
+### Transform config builder
+
+Use the script below or its `build` equivalent to transform a config builder file into a file that default exports a literally typed object like the one in the following example.
+
+```sh
+npx zcb watch ./configBuilder.ts ./builtConfig.ts
+```
+
+```ts
+// ./builtConfig.ts
+/* eslint-disable prettier/prettier, import/no-default-export, unicorn/numeric-separators-style */
+/* This file is autogenerated, do not edit directly, your changes will not perist. */
+
+export default {
+  countryCode: "GB",
+  countryName: "United Kingdom",
+  distanceUnit: "km",
+  languageCodes: [
+    "en"
+  ],
+  locales: [
+    "en_GB"
+  ],
+  name: "alpha",
+  pages: {
+    contactDetails: {
+      name: "contactDetails",
+      sections: [
+        {
+          name: "header"
+        },
+        {
+          name: "body",
+          sections: [
+            {
+              name: "main"
+            },
+            {
+              name: "sidebar"
+            }
+          ]
+        },
+        {
+          name: "footer"
+        }
+      ]
+    },
+    personalDetails: {
+      name: "personalDetails",
+      sections: [
+        {
+          name: "header"
+        },
+        {
+          name: "body",
+          sections: [
+            {
+              name: "main"
+            },
+            {
+              name: "sidebar"
+            }
+          ]
+        },
+        {
+          name: "footer"
+        }
+      ]
+    }
+  },
+  routes: [
+    {
+      page: "personalDetails",
+      path: "personal-details"
+    },
+    {
+      page: "contactDetails",
+      path: "contact-details"
+    }
+  ],
+  timeouts: {
+    apollo: 10000
+  },
+  timezone: "Europe/London"
+} as const;
+```
+
+#### cli API
+
+* `zcb build <input-file> <output-file>`
+
+```sh
+Write config from a config builder
+
+Positionals:
+  input-file   The relative path to the config builder root file
+                                                             [string] [required]
+  output-file  The relative path to the output config file   [string] [required]
+
+Options:
+  --version                    Show version number                     [boolean]
+  --help                       Show help                               [boolean]
+  --experiments-callback-file  The relative path to the experiment callback file
+                                                                        [string]
+```
+
+* `zcb watch <input-file> <output-file>`
+
+```sh
+Watch a config builder and write config
+
+Positionals:
+  input-file   The relative path to the config builder root file
+                                                             [string] [required]
+  output-file  The relative path to the output config file   [string] [required]
+
+Options:
+  --version                    Show version number                     [boolean]
+  --help                       Show help                               [boolean]
+  --experiments-callback-file  The relative path to the experiment callback file
+                                                                        [string]
+```
+
+### Create config reader
+
+Then use the autogenerated config to create a config reader that you can access config values with. The autogenerated config will always be a default import.
+
+```ts
+// ./configReader.ts
+import { createConfigParser, createConfigReader } from 'zcb';
+import builtConfig from './builtConfig.ts';
+
+export default () => createConfigReader(builtConfig);
+```
+
+### Use config reader
+
+Then import the config reader into the file in which you want access to config values. The config reader comes with config path autocomplete and return value preview.
+
+```ts
+import configReader from './configReader.ts';
+
+// scope config path autocompletion and validation
+const scopedReader = configReader.scope('pages.contactDetails')
+                      .scope('sections.1.sections')
+                      .scope('0');
+// reader config path autocompletion and validation
+// value and type preview
+const value = scopedReader('name');
+```
+
+#### reader API
+
+**scope: `(value: string) => Get<Config, string>`**
+
+Use to scope a reader to a slice of config, rather than having to pass in the full config path every time.
+
+---
+
+## Changelog
+
+Check out the [features, fixes and more](CHANGELOG.md) that go into each major, minor and patch version.
+
+## License
+
+zcb is [MIT Licensed](LICENSE).

package/bin/zcb.mjs

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --loader ts-node/esm
 const { cli } = await import('../dist/main/cli.mjs'); // eslint-disable-line import/no-unresolved
 cli();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zcb",
   "description": "Build configs with type safety from zod schema.",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "author": "Dylan Aubrey",
   "license": "MIT",
   "homepage": "https://github.com/badbatch/zod-config-builder",
@@ -48,23 +48,23 @@
     "@commitlint/config-conventional": "^17.6.3",
     "@commitlint/prompt-cli": "^17.6.3",
     "@jest/globals": "^29.5.0",
-    "@repodog/babel-config": "^1.0.0",
-    "@repodog/cli": "^1.1.1",
-    "@repodog/commitlint-config": "^1.0.0",
-    "@repodog/eslint-config": "^1.0.0",
-    "@repodog/jest-config": "^1.0.0",
-    "@repodog/markdownlint-config": "^1.0.0",
-    "@repodog/prettier-config": "^1.0.0",
-    "@repodog/rollup-config": "^1.0.0",
-    "@repodog/syncpack-config": "1.0.0",
-    "@repodog/ts-config": "^1.0.0",
+    "@repodog/babel-config": "^1.1.3",
+    "@repodog/cli": "^1.1.4",
+    "@repodog/commitlint-config": "^1.1.3",
+    "@repodog/eslint-config": "^1.1.3",
+    "@repodog/jest-config": "^1.1.3",
+    "@repodog/markdownlint-config": "^1.1.3",
+    "@repodog/prettier-config": "^1.1.3",
+    "@repodog/rollup-config": "^1.1.3",
+    "@repodog/syncpack-config": "^1.1.3",
+    "@repodog/ts-config": "^1.1.3",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-image": "^3.0.2",
     "@rollup/plugin-json": "^6.0.0",
     "@rollup/plugin-node-resolve": "^15.0.2",
     "@rollup/plugin-terser": "^0.4.1",
     "@types/fs-extra": "^11.0.1",
-    "@types/jest": "^29.5.1",
+    "@types/jest": "^25.1.3",
     "@types/json-schema": "^7.0.11",
     "@types/lodash": "^4.14.191",
     "@types/node": "^18.11.18",
@@ -90,7 +90,7 @@
     "eslint-plugin-sort-destructure-keys": "^1.5.0",
     "eslint-plugin-sort-keys-fix": "^1.1.2",
     "eslint-plugin-typescript-sort-keys": "^2.3.0",
-    "eslint-plugin-unicorn": "^47.0.0",
+    "eslint-plugin-unicorn": "^46.0.1",
     "generate-changelog": "^1.8.0",
     "husky": "^8.0.3",
     "identity-obj-proxy": "^3.0.0",
@@ -108,6 +108,11 @@
     "type-fest": "^3.10.0",
     "typescript": "^5.0.3"
   },
+  "keywords": [
+    "config",
+    "configuration",
+    "zod"
+  ],
   "scripts": {
     "build": "pnpm run clean:dist && pnpm run compile",
     "clean:deps": "del-cli ./node_modules",
@@ -124,6 +129,7 @@
     "test": "node --require=suppress-experimental-warnings --experimental-vm-modules node_modules/jest/bin/jest.js",
     "type-check": "tsc --noEmit",
     "validate": "syncpack format && syncpack lint-semver-ranges && pnpm run build && pnpm run lint && pnpm run type-check && pnpm run test",
+    "zcb:build": "NODE_OPTIONS=\"--loader ts-node/esm\" node ./bin/zcb.mjs build ./src/__testUtils__/configBuilder.ts ./src/__testUtils__/builtConfig.ts",
     "zcb:watch": "NODE_OPTIONS=\"--loader ts-node/esm\" node ./bin/zcb.mjs watch ./src/__testUtils__/configBuilder.ts ./src/__testUtils__/builtConfig.ts"
   }
 }

package/src/__testUtils__/builtConfig.ts

@@ -1,4 +1,5 @@
 /* eslint-disable prettier/prettier, import/no-default-export, unicorn/numeric-separators-style */
+/* This file is autogenerated, do not edit directly, your changes will not perist. */
 
 export default {
   countryCode: "GB",

package/src/__testUtils__/configReader.ts

@@ -0,0 +1,7 @@
+import { createConfigParser } from '../createConfigParser.ts';
+import { createConfigReader } from '../createConfigReader.ts';
+import buildConfig from './builtConfig.ts';
+
+const config = await createConfigParser(buildConfig);
+
+export const createReader = () => createConfigReader(config);

package/src/cli.ts

@@ -2,85 +2,65 @@ import { watchFile } from 'node:fs';
 import { resolve } from 'node:path';
 import shelljs from 'shelljs';
 import yargs from 'yargs';
-import type { ExperimentsCallback } from './types.ts';
-import { writeConfig } from './utils/writeConfig.ts';
+import { importValidateTransformWriteConfig } from './utils/importValidateTransformWriteConfig.ts';
+
+export enum Commands {
+  BUILD = 'build',
+  WATCH = 'watch',
+}
+
+const generateArguments = (cmdYargs: yargs.Argv) =>
+  cmdYargs
+    .positional('input-file', {
+      demandOption: true,
+      desc: 'The relative path to the config builder root file',
+      type: 'string',
+    })
+    .positional('output-file', {
+      demandOption: true,
+      desc: 'The relative path to the output config file',
+      type: 'string',
+    })
+    .option('experiments-callback-file', {
+      desc: 'The relative path to the experiment callback file',
+      type: 'string',
+    });
 
 export const cli = () => {
   yargs
     .command(
-      'watch <inputFile> <outputFile>',
-      'watch a config builder and write ',
-      cmdYargs =>
-        cmdYargs
-          .positional('inputFile', {
-            demandOption: true,
-            desc: 'The relative path to the config builder root file',
-            type: 'string',
-          })
-          .positional('outputFile', {
-            demandOption: true,
-            desc: 'The relative path to the output config file',
-            type: 'string',
-          })
-          .option('experiments-callback', {
-            desc: 'The relative path to the experiment callback file',
-            type: 'string',
-          }),
+      'watch <input-file> <output-file>',
+      'Watch a config builder and write config',
+      cmdYargs => generateArguments(cmdYargs),
       argv => {
-        const fullWatchFilePath = resolve(process.cwd(), argv.inputFile);
-        shelljs.echo(`zcd watch => watching file: ${argv.inputFile}`);
-
-        watchFile(fullWatchFilePath, () => {
-          import(fullWatchFilePath)
-            .then(
-              ({
-                default: configBuilder,
-              }: {
-                default: ReturnType<typeof import('./createConfigBuilder.ts')['createConfigBuilder']>;
-              }) => {
-                shelljs.echo('zcd watch => file change detected');
-
-                if (!configBuilder.validate()) {
-                  shelljs.echo('zcd watch => invalid config');
-                  shelljs.echo(`zcd watch => errors:\n${JSON.stringify(configBuilder.errors(), undefined, 2)}\n`);
-                  shelljs.exit(1);
-                }
-
-                shelljs.echo('zcd watch => valid config');
-                shelljs.echo(`zcd watch => config values:\n${configBuilder.toJson()}\n`);
-
-                if (argv['experiments-callback']) {
-                  import(resolve(process.cwd(), argv['experiments-callback']))
-                    .then(({ default: experimentsCallback }: { default: ExperimentsCallback }) => {
-                      void writeConfig(configBuilder.values(), { experimentsCallback, outputFile: argv.outputFile });
-                    })
-                    .catch((error: unknown) => {
-                      if (error instanceof Error) {
-                        shelljs.echo(`zcd watch => error message: ${error.message}`);
-
-                        if (error.stack) {
-                          shelljs.echo(`zcd watch => error stack:\n${error.stack}\n`);
-                        }
-                      }
-                    });
+        shelljs.echo(`zcd watch => watching file: ${argv['input-file']}`);
 
-                  return;
-                }
+        watchFile(resolve(process.cwd(), argv['input-file']), () => {
+          shelljs.echo('zcd watch => file change detected');
 
-                void writeConfig(configBuilder.values(), { outputFile: argv.outputFile });
-              }
-            )
-            .catch((error: unknown) => {
-              if (error instanceof Error) {
-                shelljs.echo(`zcd watch => error message: ${error.message}`);
-
-                if (error.stack) {
-                  shelljs.echo(`zcd watch => error stack:\n${error.stack}\n`);
-                }
-              }
-            });
+          importValidateTransformWriteConfig(
+            argv['input-file'],
+            argv['output-file'],
+            Commands.WATCH,
+            argv['experiments-callback-file']
+          );
         });
       }
     )
+    .command(
+      'build <input-file> <output-file>',
+      'Write config from a config builder',
+      cmdYargs => generateArguments(cmdYargs),
+      argv => {
+        shelljs.echo(`zcd build => building file: ${argv['input-file']}`);
+
+        importValidateTransformWriteConfig(
+          argv['input-file'],
+          argv['output-file'],
+          Commands.BUILD,
+          argv['experiments-callback-file']
+        );
+      }
+    )
     .help().argv;
 };

package/src/createConfigBuilder.test.ts

@@ -8,6 +8,7 @@ import {
   pageSchema,
   routeSchema,
 } from './__testUtils__/schema.ts';
+import { RESERVED_KEYWORDS } from './utils/isPropertyReservedWord.ts';
 
 describe('createConfigBuilder', () => {
   describe('when a user passes in a schema with a root type other than "object"', () => {
@@ -23,7 +24,7 @@ describe('createConfigBuilder', () => {
 
   describe('when a user uses a key in the schema that is a reserved keyword', () => {
     it('should throw an error', async () => {
-      const { RESERVED_KEYWORDS, createConfigBuilder } = await import('./createConfigBuilder.ts');
+      const { createConfigBuilder } = await import('./createConfigBuilder.ts');
 
       const invalidSchema = z.object({
         values: z.string(),

package/src/createConfigBuilder.ts

@@ -2,10 +2,11 @@ import { type JSONSchema7 } from 'json-schema';
 import { type ZodError, type z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { cloneNonEnumerableValues } from './transformers/cloneNonEnumerableValues.ts';
+import { NonEmumeralProperties } from './types.ts';
 import { arrayHasInvalidDefaults } from './utils/arrayHasInvalidDefaults.ts';
 import { isDerivedValueCallback } from './utils/isDerivedValueCallback.ts';
 import { isInvalidPropertyOverride } from './utils/isInvalidPropertyOverride.ts';
-import { isPropertyReservedWord } from './utils/isPropertyReservedWord.ts';
+import { RESERVED_KEYWORDS, isPropertyReservedWord } from './utils/isPropertyReservedWord.ts';
 import { isSchemaValid } from './utils/isSchemaValid.ts';
 import { isValidPropertyDefinition } from './utils/isValidPropertyDefinition.ts';
 import { isValidValue } from './utils/isValidValue.ts';
@@ -13,18 +14,6 @@ import { objectHasInvalidDefaults } from './utils/objectHasInvalidDefaults.ts';
 import { recordHasInvalidDefaults } from './utils/recordHasInvalidDefaults.ts';
 import { transformConfigSync } from './utils/transformConfig.ts';
 
-export const RESERVED_KEYWORDS = new Set([
-  'disable',
-  'errors',
-  'experiment',
-  'extend',
-  'flush',
-  'fork',
-  'toJson',
-  'validate',
-  'values',
-]);
-
 export const createConfigBuilder = <ZodTypes>(
   zodSchema: z.ZodSchema,
   derivedValueCallbacks: Partial<
@@ -65,7 +54,7 @@ export const createConfigBuilder = <ZodTypes>(
 
   let config = initialValues as Config;
 
-  Object.defineProperty(config, '__zcb', {
+  Object.defineProperty(config, NonEmumeralProperties.ZCB, {
     configurable: false,
     enumerable: false,
     value: true,
@@ -75,7 +64,7 @@ export const createConfigBuilder = <ZodTypes>(
 
   const configBuilder = {
     disable: () => {
-      Object.defineProperty(config, '__disabled', {
+      Object.defineProperty(config, NonEmumeralProperties.DISABLED, {
         configurable: false,
         enumerable: false,
         value: true,
@@ -92,7 +81,7 @@ export const createConfigBuilder = <ZodTypes>(
       }
     },
     experiment: (key: string) => {
-      Object.defineProperty(config, '__experiment', {
+      Object.defineProperty(config, NonEmumeralProperties.EXPERIMENT, {
         configurable: false,
         enumerable: false,
         value: key,
@@ -109,7 +98,7 @@ export const createConfigBuilder = <ZodTypes>(
       const values = configBuilder.values();
       config = {} as Config;
 
-      Object.defineProperty(config, '__zcb', {
+      Object.defineProperty(config, NonEmumeralProperties.ZCB, {
         configurable: false,
         enumerable: false,
         value: true,
@@ -141,7 +130,7 @@ export const createConfigBuilder = <ZodTypes>(
     },
   } as unknown as ConfigBuilder;
 
-  Object.defineProperty(configBuilder, '__callbacks', {
+  Object.defineProperty(configBuilder, NonEmumeralProperties.CALLBACKS, {
     configurable: false,
     enumerable: false,
     value: callbacks,

package/src/createConfigParser.ts

@@ -0,0 +1,16 @@
+import { runExperiments } from './transformers/runExperiments.ts';
+import type { ConfigParserOptions, TransformConfigHandler } from './types.ts';
+import { transformConfig } from './utils/transformConfig.ts';
+
+export const createConfigParser = async <Config extends object>(
+  config: Config,
+  { experimentsCallback }: ConfigParserOptions = {}
+) => {
+  const handlers: TransformConfigHandler[] = [];
+
+  if (experimentsCallback) {
+    handlers.push(runExperiments(experimentsCallback));
+  }
+
+  return handlers.length > 0 ? await transformConfig(config, handlers) : config;
+};

package/src/createConfigReader.test.ts

@@ -1,19 +1,17 @@
-import { config } from './__testUtils__/config.ts';
+import { createReader } from './__testUtils__/configReader.ts';
 
 describe('createConfigReader', () => {
   describe('when a user accesses a known property', () => {
-    it('should return the correct value', async () => {
-      const { createConfigReader } = await import('./createConfigReader.ts');
-      const reader = createConfigReader(config);
+    it('should return the correct value', () => {
+      const reader = createReader();
       const value = reader('countryCode');
       expect(value).toBe('GB');
     });
   });
 
   describe('when a user accesses a known nested property', () => {
-    it('should return the correct value', async () => {
-      const { createConfigReader } = await import('./createConfigReader.ts');
-      const reader = createConfigReader(config);
+    it('should return the correct value', () => {
+      const reader = createReader();
       const value = reader('pages.contactDetails.name');
       expect(value).toBe('contactDetails');
     });
@@ -21,9 +19,8 @@ describe('createConfigReader', () => {
 
   describe('when the reader is scoped', () => {
     describe('when a user accesses a known property', () => {
-      it('should return the correct value', async () => {
-        const { createConfigReader } = await import('./createConfigReader.ts');
-        const reader = createConfigReader(config);
+      it('should return the correct value', () => {
+        const reader = createReader();
         const scopedReader = reader.scope('pages.contactDetails');
         const value = scopedReader('name');
         expect(value).toBe('contactDetails');
@@ -33,9 +30,8 @@ describe('createConfigReader', () => {
 
   describe('when the reader is scoped multiple times', () => {
     describe('when a user accesses a known property', () => {
-      it('should return the correct value', async () => {
-        const { createConfigReader } = await import('./createConfigReader.ts');
-        const reader = createConfigReader(config);
+      it('should return the correct value', () => {
+        const reader = createReader();
         const scopedReader = reader.scope('pages.contactDetails').scope('sections.1.sections').scope('0');
         const value = scopedReader('name');
         expect(value).toBe('main');

package/src/createConfigReader.ts

@@ -1,12 +1,9 @@
 import get from 'lodash/get.js';
-import type { Get, Join } from 'type-fest';
-import type { Leaves, Paths } from './types.ts';
+import type { Get } from 'type-fest';
+import type { Path, Scope } from './types.ts';
 
 export const createConfigReader = <Config extends object>(config: Config) => {
-  const configReader = <Path extends Join<Leaves<Config>, '.'>>(path: Path) => get(config, path);
-
-  configReader.scope = <Scope extends Join<Paths<Config>, '.'>>(scope: Scope) =>
-    createConfigReader(get(config, scope) as Get<Config, Scope>);
-
+  const configReader = <P extends Path<Config>>(path: P) => get(config, path);
+  configReader.scope = <S extends Scope<Config>>(scope: S) => createConfigReader(get(config, scope) as Get<Config, S>);
   return configReader;
 };

package/src/index.ts

@@ -1,6 +1,9 @@
 export * from './createConfigBuilder.ts';
+export * from './createConfigParser.ts';
+export * from './createConfigReader.ts';
 export * from './data/countryCodes.ts';
 export * from './data/countryNames.ts';
 export * from './data/distanceUnits.ts';
 export * from './data/languageCodes.ts';
 export * from './data/timezones.ts';
+export * from './types.ts';

package/src/templates/config.ts.hbs

@@ -1,3 +1,4 @@
 /* eslint-disable prettier/prettier, import/no-default-export, unicorn/numeric-separators-style */
+/* This file is autogenerated, do not edit directly, your changes will not perist. */
 
 export default {{{ config }}} as const;

package/src/transformers/cloneNonEnumerableValues.ts

@@ -1,6 +1,6 @@
-import type { AnyRecord, TransformConfigHandlerSync } from '../types.ts';
+import { type AnyRecord, NonEmumeralProperties, type TransformConfigHandlerSync } from '../types.ts';
 
-const NON_ENUMERABLE_KEYS = new Set(['__disabled', '__experiment', '__zcb']);
+const NON_ENUMERABLE_KEYS = new Set(Object.values(NonEmumeralProperties));
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const cloneNonEnumerableValues: TransformConfigHandlerSync = <Config extends AnyRecord>(

package/src/transformers/removeDisabledSlices.ts

@@ -1,11 +1,16 @@
-import { type AnyRecord, TransformConfigHandlerAction, type TransformConfigHandlerSync } from '../types.ts';
+import {
+  type AnyRecord,
+  NonEmumeralProperties,
+  TransformConfigHandlerAction,
+  type TransformConfigHandlerSync,
+} from '../types.ts';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const removeDisabledSlices: TransformConfigHandlerSync = <Config extends AnyRecord>(
   clone: Config,
   config: Config
 ) => {
-  if ('__disabled' in config) {
+  if (NonEmumeralProperties.DISABLED in config) {
     return {
       action: TransformConfigHandlerAction.DELETE_NODE,
     };

package/src/transformers/runExperiments.ts

@@ -0,0 +1,24 @@
+import {
+  type AnyRecord,
+  type Buckets,
+  NonEmumeralProperties,
+  type RunExperimentsCallback,
+  type TransformConfigHandler,
+} from '../types.ts';
+
+export const runExperiments =
+  (callback: RunExperimentsCallback): TransformConfigHandler =>
+  async <Config extends AnyRecord>(clone: Config, config: Config) => {
+    if (NonEmumeralProperties.EXPERIMENT in config && typeof config.__experiment === 'object') {
+      const { buckets, id } = config.__experiment as { buckets: Buckets<Config>; id: string };
+      const bucket = await callback(id);
+
+      if (bucket && bucket in buckets && buckets[bucket]) {
+        return buckets[bucket]!;
+      }
+    }
+
+    return {
+      value: clone,
+    };
+  };

package/src/transformers/setupExperiments.ts

@@ -1,16 +1,20 @@
-import type { AnyRecord, ExperimentsCallback, TransformConfigHandler } from '../types.ts';
+import {
+  type AnyRecord,
+  NonEmumeralProperties,
+  type SetupExperimentsCallback,
+  type TransformConfigHandler,
+} from '../types.ts';
 
 export const setupExperiments =
-  (callback: ExperimentsCallback): TransformConfigHandler =>
+  (callback: SetupExperimentsCallback): TransformConfigHandler =>
   async <Config extends AnyRecord>(clone: Config, config: Config) => {
-    if ('__experiment' in config && typeof config.__experiment === 'string') {
-      const { action, value = {} } = await callback(config.__experiment, clone, config);
+    if (NonEmumeralProperties.EXPERIMENT in config && typeof config.__experiment === 'string') {
+      const buckets = await callback(config.__experiment, clone, config);
 
       // @ts-expect-error private property
       clone.__experiment = {
-        action,
+        buckets,
         id: config.__experiment,
-        value,
       };
 
       return {

package/src/types.ts

@@ -1,19 +1,38 @@
 import type { List } from 'ts-toolbelt';
-import type { Includes } from 'type-fest';
+import type { Includes, Join } from 'type-fest';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyRecord = Record<string, any>;
 
-export interface WriteConfigOptions {
-  experimentsCallback?: ExperimentsCallback;
-  outputFile: string;
+export type Buckets<Config extends AnyRecord> = Record<string, Experiment<Config>>;
+
+export interface ConfigParserOptions {
+  experimentsCallback?: RunExperimentsCallback;
+}
+
+export interface Experiment<Config extends AnyRecord> {
+  action?: TransformConfigHandlerAction;
+  value?: Config;
+}
+
+export enum NonEmumeralProperties {
+  CALLBACKS = '__callbacks',
+  DISABLED = '__disabled',
+  EXPERIMENT = '__experiment',
+  ZCB = '__zcb',
 }
 
-export type ExperimentsCallback = <Config extends AnyRecord>(
+export type Path<Config extends object> = Join<Leaves<Config>, '.'>;
+
+export type RunExperimentsCallback = (id: string) => Promise<string>;
+
+export type Scope<Config extends object> = Join<Paths<Config>, '.'>;
+
+export type SetupExperimentsCallback = <Config extends AnyRecord>(
   id: string,
   clone: Config,
   config: Config
-) => Promise<TransformConfigHandlerReturnType<Config>>;
+) => Promise<Buckets<Config>>;
 
 export type TransformConfigHandler = <Config extends AnyRecord>(
   clone: Config,
@@ -35,6 +54,11 @@ export interface TransformConfigHandlerReturnType<Config extends AnyRecord> {
   value?: Config;
 }
 
+export interface WriteConfigOptions {
+  experimentsCallback?: SetupExperimentsCallback;
+  outputFile: string;
+}
+
 export type Leaves<T, Path extends string[] = []> = T extends string
   ? Path
   : {

package/src/utils/importValidateTransformWriteConfig.ts

@@ -0,0 +1,60 @@
+import { resolve } from 'node:path';
+import shelljs from 'shelljs';
+import type { Commands } from '../cli.ts';
+import type { SetupExperimentsCallback } from '../types.ts';
+import { transformWriteConfig } from './transformWriteConfig.ts';
+
+export const importValidateTransformWriteConfig = (
+  inputFile: string,
+  outputFile: string,
+  command: Commands,
+  experimentCallbackFile?: string
+) => {
+  import(resolve(process.cwd(), inputFile))
+    .then(
+      ({
+        default: configBuilder,
+      }: {
+        default: ReturnType<typeof import('../createConfigBuilder.ts')['createConfigBuilder']>;
+      }) => {
+        if (!configBuilder.validate()) {
+          shelljs.echo(`zcd ${command} => invalid config`);
+          shelljs.echo(`zcd ${command} => config values:\n${configBuilder.toJson()}\n`);
+          shelljs.echo(`zcd ${command} => errors:\n${JSON.stringify(configBuilder.errors(), undefined, 2)}\n`);
+          shelljs.exit(1);
+        }
+
+        shelljs.echo('zcd ${command} => valid config');
+        shelljs.echo(`zcd ${command} => config values:\n${configBuilder.toJson()}\n`);
+
+        if (experimentCallbackFile) {
+          import(resolve(process.cwd(), experimentCallbackFile))
+            .then(({ default: experimentsCallback }: { default: SetupExperimentsCallback }) => {
+              void transformWriteConfig(configBuilder.values(), { experimentsCallback, outputFile });
+            })
+            .catch((error: unknown) => {
+              if (error instanceof Error) {
+                shelljs.echo(`zcd ${command} => error message: ${error.message}`);
+
+                if (error.stack) {
+                  shelljs.echo(`zcd ${command} => error stack:\n${error.stack}\n`);
+                }
+              }
+            });
+
+          return;
+        }
+
+        void transformWriteConfig(configBuilder.values(), { outputFile });
+      }
+    )
+    .catch((error: unknown) => {
+      if (error instanceof Error) {
+        shelljs.echo(`zcd ${command} => error message: ${error.message}`);
+
+        if (error.stack) {
+          shelljs.echo(`zcd ${command} => error stack:\n${error.stack}\n`);
+        }
+      }
+    });
+};

package/src/utils/isPropertyReservedWord.ts

@@ -1,3 +1,13 @@
-import { RESERVED_KEYWORDS } from '../createConfigBuilder.ts';
+export const RESERVED_KEYWORDS = new Set([
+  'disable',
+  'errors',
+  'experiment',
+  'extend',
+  'flush',
+  'fork',
+  'toJson',
+  'validate',
+  'values',
+]);
 
 export const isPropertyReservedWord = (propertyName: string) => RESERVED_KEYWORDS.has(propertyName);

package/src/utils/{writeConfig.ts → transformWriteConfig.ts}

@@ -9,7 +9,7 @@ import { setupExperiments } from '../transformers/setupExperiments.ts';
 import type { TransformConfigHandler, WriteConfigOptions } from '../types.ts';
 import { transformConfig } from './transformConfig.ts';
 
-export const writeConfig = async <Config extends object>(
+export const transformWriteConfig = async <Config extends object>(
   config: Config,
   { experimentsCallback, outputFile }: WriteConfigOptions
 ) => {
@@ -30,5 +30,5 @@ export const writeConfig = async <Config extends object>(
 
   shelljs.echo(`zcd watch => writing to file: ${outputFile}`);
   shelljs.echo(`zcd watch => content to write:\n${output}\n`);
-  outputFileSync(outputFile, output);
+  outputFileSync(resolve(process.cwd(), outputFile), output);
 };