@zamatica/configuration 0.1.0

package/src/parameter-builder.ts

@@ -0,0 +1,190 @@
+import type { z } from 'zod';
+import type {
+  ConfigurationParameterDefinition,
+  ConfigurationValueConstructor,
+  ConfigurationValuePrimitive,
+  DirectoryConfigurationParameterDefinition,
+  SimpleConfigurationParameterDefinition,
+  YamlConfigurationParameterDefinition,
+} from './parameter-types.js';
+
+const ENV_VAR_NAME_REGEX = /^[A-Z]([A-Z0-9_]*[A-Z0-9])?$/;
+
+function assertValidConfigurationKey(key: string): void {
+  if (!ENV_VAR_NAME_REGEX.test(key)) {
+    throw new Error(
+      `Invalid configuration key '${key}': must match SCREAMING_SNAKE_CASE (env-var convention).`,
+    );
+  }
+}
+
+interface BaseState {
+  key: string;
+  description: string;
+  required: boolean;
+  default: ConfigurationValuePrimitive | undefined;
+}
+
+/**
+ * Common methods shared by every parameter builder. Subclasses add type-specific
+ * methods (e.g. `requireWritable()` on directory builders) and implement `build()`.
+ *
+ * The builder mutates `this.state` and returns `this` for chaining; subclasses
+ * preserve that pattern so chains compose cleanly.
+ */
+abstract class ParameterBuilderBase<TSelf extends ParameterBuilderBase<TSelf, TDef>, TDef> {
+  protected state: BaseState;
+
+  protected constructor(state: BaseState) {
+    this.state = state;
+  }
+
+  description(text: string): TSelf {
+    this.state = { ...this.state, description: text };
+    return this as unknown as TSelf;
+  }
+
+  default(value: ConfigurationValuePrimitive): TSelf {
+    this.state = { ...this.state, default: value };
+    return this as unknown as TSelf;
+  }
+
+  required(): TSelf {
+    this.state = { ...this.state, required: true };
+    return this as unknown as TSelf;
+  }
+
+  optional(): TSelf {
+    this.state = { ...this.state, required: false };
+    return this as unknown as TSelf;
+  }
+
+  abstract build(): TDef;
+}
+
+class SimpleParameterBuilder extends ParameterBuilderBase<
+  SimpleParameterBuilder,
+  SimpleConfigurationParameterDefinition
+> {
+  constructor(state: BaseState, private readonly constructorFn: ConfigurationValueConstructor) {
+    super(state);
+  }
+
+  build(): SimpleConfigurationParameterDefinition {
+    return {
+      kind: 'simple',
+      configurationKey: this.state.key,
+      description: this.state.description,
+      required: this.state.required,
+      default: this.state.default,
+      constructor: this.constructorFn,
+    };
+  }
+}
+
+class DirectoryParameterBuilder extends ParameterBuilderBase<
+  DirectoryParameterBuilder,
+  DirectoryConfigurationParameterDefinition
+> {
+  private requireWritableFlag = false;
+  private createIfMissingFlag = false;
+
+  constructor(state: BaseState) {
+    super(state);
+  }
+
+  requireWritable(): this {
+    this.requireWritableFlag = true;
+    return this;
+  }
+
+  createIfMissing(): this {
+    this.createIfMissingFlag = true;
+    return this;
+  }
+
+  build(): DirectoryConfigurationParameterDefinition {
+    return {
+      kind: 'directory',
+      configurationKey: this.state.key,
+      description: this.state.description,
+      required: this.state.required,
+      default: this.state.default,
+      constructor: String,
+      requireWritable: this.requireWritableFlag,
+      createIfMissing: this.createIfMissingFlag,
+    };
+  }
+}
+
+class YamlParameterBuilder<TSchema extends z.ZodTypeAny = z.ZodTypeAny> extends ParameterBuilderBase<
+  YamlParameterBuilder<TSchema>,
+  YamlConfigurationParameterDefinition<TSchema>
+> {
+  private schemaValue: TSchema | undefined;
+
+  constructor(state: BaseState) {
+    super(state);
+  }
+
+  schema<TNewSchema extends z.ZodTypeAny>(schema: TNewSchema): YamlParameterBuilder<TNewSchema> {
+    const next = new YamlParameterBuilder<TNewSchema>(this.state);
+    next.schemaValue = schema;
+    return next;
+  }
+
+  build(): YamlConfigurationParameterDefinition<TSchema> {
+    return {
+      kind: 'yaml',
+      configurationKey: this.state.key,
+      description: this.state.description,
+      required: this.state.required,
+      default: this.state.default,
+      constructor: String,
+      schema: this.schemaValue,
+    };
+  }
+}
+
+class ParameterTypeSelector {
+  constructor(private readonly state: BaseState) {}
+
+  string(): SimpleParameterBuilder {
+    return new SimpleParameterBuilder(this.state, String);
+  }
+
+  number(): SimpleParameterBuilder {
+    return new SimpleParameterBuilder(this.state, Number);
+  }
+
+  boolean(): SimpleParameterBuilder {
+    return new SimpleParameterBuilder(this.state, Boolean);
+  }
+
+  directory(): DirectoryParameterBuilder {
+    return new DirectoryParameterBuilder(this.state);
+  }
+
+  yaml(): YamlParameterBuilder {
+    return new YamlParameterBuilder(this.state);
+  }
+}
+
+export const ConfigurationParameter = {
+  named(key: string): ParameterTypeSelector {
+    assertValidConfigurationKey(key);
+    return new ParameterTypeSelector({
+      key,
+      description: '',
+      required: false,
+      default: undefined,
+    });
+  },
+};
+
+export type AnyConfigurationParameterBuilder =
+  | SimpleParameterBuilder
+  | DirectoryParameterBuilder
+  | YamlParameterBuilder;
+
+export type AnyConfigurationParameterDefinition = ConfigurationParameterDefinition;

package/src/parameter-types.ts

@@ -0,0 +1,41 @@
+import type { z } from 'zod';
+
+export type ConfigurationValuePrimitive = string | number | boolean;
+
+export type ConfigurationValueConstructor =
+  | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor;
+
+export interface ConfigurationParameterDefinitionBase {
+  configurationKey: string;
+  description: string;
+  required: boolean;
+  default: ConfigurationValuePrimitive | undefined;
+}
+
+export interface SimpleConfigurationParameterDefinition
+  extends ConfigurationParameterDefinitionBase {
+  kind: 'simple';
+  constructor: ConfigurationValueConstructor;
+}
+
+export interface DirectoryConfigurationParameterDefinition
+  extends ConfigurationParameterDefinitionBase {
+  kind: 'directory';
+  constructor: StringConstructor;
+  requireWritable: boolean;
+  createIfMissing: boolean;
+}
+
+export interface YamlConfigurationParameterDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny>
+  extends ConfigurationParameterDefinitionBase {
+  kind: 'yaml';
+  constructor: StringConstructor;
+  schema: TSchema | undefined;
+}
+
+export type ConfigurationParameterDefinition =
+  | SimpleConfigurationParameterDefinition
+  | DirectoryConfigurationParameterDefinition
+  | YamlConfigurationParameterDefinition;