zcb 0.0.7 → 0.0.8

package/README.md

@@ -23,6 +23,7 @@ npm install zcb
 * [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
 
@@ -31,11 +32,13 @@ Create the schema for your configuration like in the example below.
 ```ts
 // ./schema.ts
 import { z } from 'zod';
-import { countryCodes } from '../data/countryCodes.ts';
-import { countryNames } from '../data/countryNames.ts';
-import { distanceUnits } from '../data/distanceUnits.ts';
-import { languageCodes } from '../data/languageCodes.ts';
-import { timezones } from '../data/timezones.ts';
+import {
+  countryCodes,
+  countryNames,
+  distanceUnits,
+  languageCodes,
+  timezones,
+} from 'zcb';
 
 export const baseSectionSchema = z.object({
   name: z.string(),
@@ -90,7 +93,7 @@ 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.
+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
@@ -280,17 +283,63 @@ export default {
 } 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 config reader comes with config path autocomplete and return value preview. The autogenerated config will always be a default import.
+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 builtConfig from '.builtConfig.ts';
-import { createConfigReader } from 'zcb';
+import configReader from './configReader.ts';
 
-const reader = createConfigReader(builtConfig);
 // scope config path autocompletion and validation
-const scopedReader = reader.scope('pages.contactDetails')
+const scopedReader = configReader.scope('pages.contactDetails')
                       .scope('sections.1.sections')
                       .scope('0');
 // reader config path autocompletion and validation

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zcb",
   "description": "Build configs with type safety from zod schema.",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "author": "Dylan Aubrey",
   "license": "MIT",
   "homepage": "https://github.com/badbatch/zod-config-builder",

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,7 +2,7 @@ import { watchFile } from 'node:fs';
 import { resolve } from 'node:path';
 import shelljs from 'shelljs';
 import yargs from 'yargs';
-import { importValidateWriteConfig } from './utils/importValidateWriteConfig.ts';
+import { importValidateTransformWriteConfig } from './utils/importValidateTransformWriteConfig.ts';
 
 export enum Commands {
   BUILD = 'build',
@@ -38,7 +38,7 @@ export const cli = () => {
         watchFile(resolve(process.cwd(), argv['input-file']), () => {
           shelljs.echo('zcd watch => file change detected');
 
-          importValidateWriteConfig(
+          importValidateTransformWriteConfig(
             argv['input-file'],
             argv['output-file'],
             Commands.WATCH,
@@ -54,7 +54,7 @@ export const cli = () => {
       argv => {
         shelljs.echo(`zcd build => building file: ${argv['input-file']}`);
 
-        importValidateWriteConfig(
+        importValidateTransformWriteConfig(
           argv['input-file'],
           argv['output-file'],
           Commands.BUILD,

package/src/createConfigBuilder.ts

@@ -2,6 +2,7 @@ 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';
@@ -53,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,
@@ -63,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,
@@ -80,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,
@@ -97,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,
@@ -129,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,4 +1,5 @@
 export * from './createConfigBuilder.ts';
+export * from './createConfigParser.ts';
 export * from './createConfigReader.ts';
 export * from './data/countryCodes.ts';
 export * from './data/countryNames.ts';

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/{importValidateWriteConfig.ts → importValidateTransformWriteConfig.ts}

@@ -1,10 +1,10 @@
 import { resolve } from 'node:path';
 import shelljs from 'shelljs';
 import type { Commands } from '../cli.ts';
-import type { ExperimentsCallback } from '../types.ts';
-import { writeConfig } from './writeConfig.ts';
+import type { SetupExperimentsCallback } from '../types.ts';
+import { transformWriteConfig } from './transformWriteConfig.ts';
 
-export const importValidateWriteConfig = (
+export const importValidateTransformWriteConfig = (
   inputFile: string,
   outputFile: string,
   command: Commands,
@@ -19,6 +19,7 @@ export const importValidateWriteConfig = (
       }) => {
         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);
         }
@@ -28,8 +29,8 @@ export const importValidateWriteConfig = (
 
         if (experimentCallbackFile) {
           import(resolve(process.cwd(), experimentCallbackFile))
-            .then(({ default: experimentsCallback }: { default: ExperimentsCallback }) => {
-              void writeConfig(configBuilder.values(), { experimentsCallback, outputFile });
+            .then(({ default: experimentsCallback }: { default: SetupExperimentsCallback }) => {
+              void transformWriteConfig(configBuilder.values(), { experimentsCallback, outputFile });
             })
             .catch((error: unknown) => {
               if (error instanceof Error) {
@@ -44,7 +45,7 @@ export const importValidateWriteConfig = (
           return;
         }
 
-        void writeConfig(configBuilder.values(), { outputFile });
+        void transformWriteConfig(configBuilder.values(), { outputFile });
       }
     )
     .catch((error: unknown) => {

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
 ) => {