@config-bound/schema-export 0.1.0

package/src/schemaFormatters.spec.ts

@@ -0,0 +1,188 @@
+import {
+  formatAsJSON,
+  formatAsYAML,
+  formatAsEnvExample
+} from './schemaFormatters.js';
+import { ExportedSchema } from './schemaExporter.js';
+
+describe('Schema Formatters', () => {
+  const mockSchema: ExportedSchema = {
+    name: 'testApp',
+    sections: [
+      {
+        name: 'app',
+        description: 'Application settings',
+        elements: [
+          {
+            name: 'port',
+            description: 'Server port',
+            type: 'number',
+            default: 3000,
+            example: 8080,
+            required: false,
+            sensitive: false,
+            joiValidation: {
+              type: 'number',
+              rules: [
+                { name: 'min', args: { limit: 1 } },
+                { name: 'max', args: { limit: 65535 } }
+              ]
+            }
+          },
+          {
+            name: 'apiKey',
+            description: 'API key',
+            type: 'string',
+            default: undefined,
+            example: 'sk_test_123',
+            required: true,
+            sensitive: true,
+            joiValidation: { type: 'string', flags: { presence: 'required' } }
+          }
+        ]
+      },
+      {
+        name: 'database',
+        description: 'Database configuration',
+        elements: [
+          {
+            name: 'host',
+            description: 'Database host',
+            type: 'string',
+            default: 'localhost',
+            example: undefined,
+            required: false,
+            sensitive: false,
+            joiValidation: { type: 'string' }
+          }
+        ]
+      }
+    ]
+  };
+
+  describe('formatAsJSON', () => {
+    it('should format schema as pretty JSON', () => {
+      const result = formatAsJSON(mockSchema, true);
+
+      expect(result).toContain('"name": "testApp"');
+      expect(result).toContain('"port"');
+      expect(result).toContain('"database"');
+      expect(JSON.parse(result)).toEqual(mockSchema);
+    });
+
+    it('should format schema as compact JSON', () => {
+      const result = formatAsJSON(mockSchema, false);
+
+      expect(result).not.toContain('\n');
+      expect(JSON.parse(result)).toEqual(mockSchema);
+    });
+  });
+
+  describe('formatAsYAML', () => {
+    it('should format schema as YAML', () => {
+      const result = formatAsYAML(mockSchema);
+
+      expect(result).toContain('name: testApp');
+      expect(result).toContain('- name: port');
+      expect(result).toContain('- name: database');
+      expect(result).toBeTruthy();
+    });
+  });
+
+  describe('formatAsEnvExample', () => {
+    it('should format schema as .env.example without prefix', () => {
+      const result = formatAsEnvExample(mockSchema);
+
+      expect(result).toContain('# testApp Configuration');
+      expect(result).toContain('# Generated from schema export');
+      expect(result).toContain('APP_PORT=');
+      expect(result).toContain('APP_APIKEY=');
+      expect(result).toContain('DATABASE_HOST=');
+      expect(result).toContain('# Server port');
+      expect(result).toContain('# API key');
+      expect(result).toContain('# Database host');
+    });
+
+    it('should format schema as .env.example with prefix', () => {
+      const result = formatAsEnvExample(mockSchema, 'MYAPP');
+
+      expect(result).toContain('MYAPP_APP_PORT=');
+      expect(result).toContain('MYAPP_APP_APIKEY=');
+      expect(result).toContain('MYAPP_DATABASE_HOST=');
+    });
+
+    it('should include example values when available', () => {
+      const result = formatAsEnvExample(mockSchema);
+
+      expect(result).toContain('APP_PORT=8080');
+    });
+
+    it('should include default values when example is not available', () => {
+      const result = formatAsEnvExample(mockSchema);
+
+      expect(result).toContain('DATABASE_HOST=localhost');
+    });
+
+    it('should use placeholder for sensitive values', () => {
+      const result = formatAsEnvExample(mockSchema);
+
+      expect(result).toContain('APP_APIKEY=your-example-value');
+    });
+
+    it('should mark required fields', () => {
+      const result = formatAsEnvExample(mockSchema);
+
+      expect(result).toContain('# API key (required)');
+    });
+
+    it('should handle sections without descriptions', () => {
+      const schemaWithoutDesc: ExportedSchema = {
+        name: 'test',
+        sections: [
+          {
+            name: 'app',
+            elements: [
+              {
+                name: 'port',
+                type: 'number',
+                default: 3000,
+                required: false,
+                sensitive: false,
+                joiValidation: {}
+              }
+            ]
+          }
+        ]
+      };
+
+      const result = formatAsEnvExample(schemaWithoutDesc);
+      expect(result).toContain('APP_PORT=3000');
+    });
+
+    it('should handle elements without descriptions', () => {
+      const schemaWithoutElementDesc: ExportedSchema = {
+        name: 'test',
+        sections: [
+          {
+            name: 'app',
+            description: 'App config',
+            elements: [
+              {
+                name: 'port',
+                type: 'number',
+                default: 3000,
+                required: false,
+                sensitive: false,
+                joiValidation: {}
+              }
+            ]
+          }
+        ]
+      };
+
+      const result = formatAsEnvExample(schemaWithoutElementDesc);
+      expect(result).toContain('# App config');
+      expect(result).toContain('APP_PORT=3000');
+    });
+  });
+});

package/src/schemaFormatters.ts

@@ -0,0 +1,124 @@
+import yaml from 'js-yaml';
+import { ExportedSchema, ExportedElement } from './schemaExporter.js';
+
+/**
+ * Formats the schema as JSON string
+ * @param schema - The schema to format
+ * @param pretty - Whether to pretty print the JSON
+ * @returns The configuration schema as a JSON string
+ */
+export function formatAsJSON(
+  schema: ExportedSchema,
+  pretty: boolean = true
+): string {
+  return JSON.stringify(schema, null, pretty ? 2 : 0);
+}
+
+/**
+ * Formats the schema as YAML string
+ * @param schema - The schema to format
+ * @returns The configuration schema as a YAML string
+ */
+export function formatAsYAML(schema: ExportedSchema): string {
+  return yaml.dump(schema, {
+    indent: 2,
+    lineWidth: 80,
+    noRefs: true
+  });
+}
+
+/**
+ * Generates an environment variable name from section and element names
+ * @param sectionName - The name of the section
+ * @param elementName - The name of the element
+ * @param prefix - Optional prefix for the environment variable name
+ * @returns The environment variable name
+ */
+function generateEnvVarName(
+  sectionName: string,
+  elementName: string,
+  prefix?: string
+): string {
+  let name = `${sectionName}_${elementName}`.replace(/\./g, '_');
+  if (prefix) {
+    name = `${prefix}_${name}`;
+  }
+  return name.toUpperCase();
+}
+
+/**
+ * Formats a value for display in .env.example file
+ * @param element - The element to format
+ * @returns The formatted value
+ */
+function formatEnvValue(element: ExportedElement): string {
+  if (element.sensitive) {
+    if (element.example !== undefined) {
+      return 'your-example-value';
+    }
+    return 'your-secret-value';
+  }
+
+  if (element.example !== undefined) {
+    return String(element.example);
+  }
+
+  if (element.default !== undefined) {
+    return String(element.default);
+  }
+
+  switch (element.type) {
+    case 'string':
+      return 'your-value';
+    case 'number':
+      return '0';
+    case 'boolean':
+      return 'true';
+    case 'array':
+      return 'value1,value2';
+    default:
+      return 'your-value';
+  }
+}
+
+/**
+ * Formats the schema as a .env.example file
+ * @param schema - The exported schema
+ * @param prefix - Optional prefix for environment variable names (e.g., 'MYAPP')
+ * @returns The .env.example file content as a string
+ */
+export function formatAsEnvExample(
+  schema: ExportedSchema,
+  prefix?: string
+): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${schema.name} Configuration`);
+  lines.push('# Generated from schema export');
+  lines.push('');
+
+  for (const section of schema.sections) {
+    if (section.description) {
+      lines.push(`# ${section.description}`);
+    }
+
+    for (const element of section.elements) {
+      const envVarName = generateEnvVarName(section.name, element.name, prefix);
+      const value = formatEnvValue(element);
+      const isRequired = element.required && element.default === undefined;
+
+      if (element.description) {
+        lines.push(
+          `# ${element.description}${isRequired ? ' (required)' : ''}`
+        );
+      } else if (isRequired) {
+        lines.push('# Required');
+      }
+
+      lines.push(`${envVarName}=${value}`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "@config-bound/typescript-config/package.tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*", "src/**/*.spec.ts"]
+}