react-native-config-ultimate 0.0.1

package/src/render-env.ts

@@ -0,0 +1,115 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import handlebars from 'handlebars';
+
+import type { FlatConfig } from './flatten';
+import type { RC } from './resolve-env';
+import type { FileMap } from './write-env';
+
+const code_file_name = 'ConfigValues';
+const config_file_name = 'rncu';
+
+// ─── Handlebars helpers (registered once at module load, not per-call) ────────
+
+function is_string(value: unknown): boolean {
+  return typeof value === 'string';
+}
+
+function is_number(value: unknown): boolean {
+  return typeof value === 'number';
+}
+
+function is_boolean(value: unknown): boolean {
+  return typeof value === 'boolean';
+}
+
+function escape(value: unknown): unknown {
+  if (is_string(value)) {
+    return (value as string).replace(/"/gm, '\\"');
+  }
+  return value;
+}
+
+function xcconfig_format(value: unknown): unknown {
+  if (is_string(value)) {
+    return (value as string).replace(/\/\//gm, '/$()/');
+  }
+  return value;
+}
+
+function to_json(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+handlebars.registerHelper('isBoolean', is_boolean);
+handlebars.registerHelper('isString', is_string);
+handlebars.registerHelper('isNumber', is_number);
+handlebars.registerHelper('escape', escape);
+handlebars.registerHelper('xcconfigFormat', xcconfig_format);
+handlebars.registerHelper('toJSON', to_json);
+
+// ─── Template cache (compiled once per template name, not per build) ──────────
+
+const template_cache = new Map<string, HandlebarsTemplateDelegate>();
+
+function get_compiled_template(template_name: string): HandlebarsTemplateDelegate {
+  const cached = template_cache.get(template_name);
+  if (cached) return cached;
+
+  const template_path = path.join(
+    __dirname,
+    'templates',
+    `${template_name}.handlebars`
+  );
+  const compiled = handlebars.compile(fs.readFileSync(template_path, 'utf8'));
+  template_cache.set(template_name, compiled);
+  return compiled;
+}
+
+function render_template(template_name: string, data: unknown): string {
+  return get_compiled_template(template_name)(data);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+interface PlatformEnv {
+  ios: FlatConfig;
+  android: FlatConfig;
+  web: FlatConfig;
+}
+
+export default function render_env(
+  project_root: string,
+  lib_root: string,
+  env: PlatformEnv,
+  rc?: RC
+): FileMap {
+  const { ios, android, web } = env;
+  const map: FileMap = {
+    [path.join(lib_root, 'index.d.ts')]: render_template('index.d.ts', ios),
+    [path.join(lib_root, 'index.web.js')]: render_template('index.web.js', web),
+    [path.join(lib_root, 'ios', `${code_file_name}.h`)]: render_template(
+      'ConfigValues.h',
+      ios
+    ),
+    [path.join(lib_root, 'android', 'rncu.yaml')]: render_template(
+      'rncu.yaml',
+      android
+    ),
+  };
+
+  // Only write xcconfig if the project has an ios folder.
+  // All RN apps have it; some react-native-web apps may not.
+  if (fs.existsSync(path.join(project_root, 'ios'))) {
+    map[path.join(project_root, 'ios', `${config_file_name}.xcconfig`)] =
+      render_template('rncu.xcconfig', ios);
+  }
+
+  const js_override = rc && typeof rc.js_override === 'boolean' && rc.js_override;
+  map[path.join(lib_root, 'override.js')] = render_template('override.js', {
+    ios: js_override ? ios : {},
+    android: js_override ? android : {},
+  });
+
+  return map;
+}

package/src/resolve-env.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = resolve_env;
+async function resolve_env(env, rc) {
+    if (rc && rc.on_env) {
+        const patched_env = await rc.on_env(env);
+        return typeof patched_env === 'undefined' ? env : patched_env;
+    }
+    else {
+        return env;
+    }
+}

package/src/resolve-env.spec.ts

@@ -0,0 +1,25 @@
+import resolve_env from './resolve-env';
+import type { EnvData } from './resolve-env';
+
+describe('resolve_env', () => {
+  const original: EnvData = { original: 'data' };
+  it.each`
+    on_env_result | expected
+    ${1}          | ${1}
+    ${''}         | ${''}
+    ${'hello'}    | ${'hello'}
+    ${0}          | ${0}
+    ${1}          | ${1}
+    ${false}      | ${false}
+    ${true}       | ${true}
+    ${null}       | ${null}
+    ${undefined}  | ${original}
+  `(
+    "when hook returns '$on_env_result' env is resolved to '$expected'",
+    async ({ on_env_result, expected }: { on_env_result: unknown; expected: unknown }) => {
+      const on_env = jest.fn();
+      on_env.mockReturnValueOnce(on_env_result);
+      expect(await resolve_env(original, { on_env })).toEqual(expected);
+    }
+  );
+});

package/src/resolve-env.ts

@@ -0,0 +1,45 @@
+export type EnvData = Record<string, unknown>;
+
+/**
+ * Schema definition for a single environment variable.
+ * Used in `.rncurc.js` to validate env vars at build time.
+ *
+ * @example
+ * module.exports = {
+ *   schema: {
+ *     API_URL:    { type: 'string',  required: true },
+ *     TIMEOUT_MS: { type: 'number',  required: true },
+ *     DEBUG:      { type: 'boolean', required: false },
+ *     ENV_NAME:   { type: 'string',  required: true, pattern: '^(dev|staging|prod)$' },
+ *   }
+ * };
+ */
+export interface SchemaField {
+  /** Expected type. Strings are always accepted as-is; number/boolean validate parsability. */
+  type: 'string' | 'number' | 'boolean';
+  /** If true, build fails when this var is missing or empty. Default: false. */
+  required?: boolean;
+  /** Optional regex pattern the value must match (applied to string representation). */
+  pattern?: string;
+}
+
+export type Schema = Record<string, SchemaField>;
+
+export interface RC {
+  on_env?: (env: EnvData) => unknown;
+  js_override?: boolean;
+  /**
+   * Optional schema for build-time validation of env vars.
+   * Validated after `on_env` runs (so the hook can add/transform vars before validation).
+   */
+  schema?: Schema;
+}
+
+export default async function resolve_env(env: EnvData, rc?: RC): Promise<EnvData> {
+  if (rc && rc.on_env) {
+    const patched_env = await rc.on_env(env);
+    return typeof patched_env === 'undefined' ? env : (patched_env as EnvData);
+  } else {
+    return env;
+  }
+}

package/src/templates/ConfigValues.h.handlebars

@@ -0,0 +1,24 @@
+// DO NOT COMMIT OR EDIT THIS FILE
+{{#each @root}}
+{{#if (isString this)}}
+#define {{@key}} @"{{{escape this}}}"
+{{/if}}
+{{#if (isBoolean this)}}
+{{#if this}}
+#define {{@key}} @(YES)
+{{else}}
+#define {{@key}} @(NO)
+{{/if}}
+{{/if}}
+{{#if (isNumber this)}}
+#define {{@key}} @({{{this}}})
+{{/if}}
+{{/each}}
+
+static NSDictionary *getValues() {
+    return @{
+        {{#each @root}}
+        @"{{@key}}": {{@key}},
+        {{/each}}
+    };
+}

package/src/templates/index.d.ts.handlebars

@@ -0,0 +1,18 @@
+// DO NOT COMMIT OR EDIT THIS FILE
+export interface ConfigVariables {
+{{#each @root}}
+{{#if (isString this)}}
+  {{@key}}: string;
+{{/if}}
+{{#if (isBoolean this)}}
+  {{@key}}: boolean;
+{{/if}}
+{{#if (isNumber this)}}
+  {{@key}}: number;
+{{/if}}
+{{/each}}
+}
+
+declare const UltimateConfig: ConfigVariables;
+
+export default UltimateConfig;

package/src/templates/index.web.js.handlebars

@@ -0,0 +1 @@
+module.exports = {{{toJSON @root}}}

package/src/templates/override.js.handlebars

@@ -0,0 +1,16 @@
+const RN = require("react-native");
+
+const IOS_DATA = {{{toJSON @root.ios}}}
+
+const ANDROID_DATA = {{{toJSON @root.android}}}
+
+module.exports = {
+{{#each @root.ios}}
+  get {{{@key}}}() {
+    return RN.Platform.select({
+      ios: IOS_DATA["{{{@key}}}"],
+      android: ANDROID_DATA["{{{@key}}}"],
+    });
+  },
+{{/each}}
+}

package/src/templates/rncu.xcconfig.handlebars

@@ -0,0 +1,4 @@
+// DO NOT COMMIT OR EDIT THIS FILE
+{{#each @root}}
+{{@key}}={{{xcconfigFormat this}}}
+{{/each}}

package/src/templates/rncu.yaml.handlebars

@@ -0,0 +1,7 @@
+{{#each @root}}
+{{#if (isString this)}}
+{{@key}}: "{{{escape this}}}"
+{{else}}
+{{@key}}: {{{this}}}
+{{/if}}
+{{/each}}

package/src/validate-env.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate_env = validate_env;
+/**
+ * Validate env data against a schema defined in `.rncurc.js`.
+ * Called after `on_env` so the hook can add/transform vars before validation.
+ *
+ * Throws with a human-readable error listing ALL failures at once
+ * (not just the first one), so users can fix everything in one pass.
+ */
+function validate_env(env, schema) {
+    const errors = [];
+    // Pre-compile all regex patterns once, before iterating over env values.
+    // This avoids re-compiling the same pattern for every validated key.
+    const compiled_patterns = new Map();
+    for (const [key, field] of Object.entries(schema)) {
+        if (field.pattern) {
+            try {
+                compiled_patterns.set(key, new RegExp(field.pattern));
+            }
+            catch (_a) {
+                errors.push(`${key}: invalid regex pattern /${field.pattern}/`);
+            }
+        }
+    }
+    for (const [key, field] of Object.entries(schema)) {
+        const raw = env[key];
+        const missing = raw === undefined || raw === null || String(raw).trim() === '';
+        if (field.required && missing) {
+            errors.push(`Missing required env var: ${key}`);
+            continue; // can't type-check a missing value
+        }
+        if (missing)
+            continue; // optional and not present → OK
+        const value = String(raw);
+        if (field.type === 'number' && isNaN(Number(value))) {
+            errors.push(`${key} must be a number, got "${value}"`);
+        }
+        if (field.type === 'boolean' &&
+            !['true', 'false', '1', '0'].includes(value.toLowerCase())) {
+            errors.push(`${key} must be a boolean (true/false/1/0), got "${value}"`);
+        }
+        const pattern = compiled_patterns.get(key);
+        if (pattern && !pattern.test(value)) {
+            errors.push(`${key} does not match pattern /${field.pattern}/, got "${value}"`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`\n\n❌ react-native-config-ultimate: env validation failed:\n` +
+            errors.map((e) => `  • ${e}`).join('\n') +
+            '\n');
+    }
+}

package/src/validate-env.spec.ts

@@ -0,0 +1,164 @@
+import { validate_env } from './validate-env';
+import type { Schema } from './resolve-env';
+
+describe('validate-env', () => {
+  describe('required fields', () => {
+    it('throws when a required var is missing', () => {
+      const schema: Schema = { API_KEY: { type: 'string', required: true } };
+      expect(() => validate_env({}, schema)).toThrow('Missing required env var: API_KEY');
+    });
+
+    it('throws when a required var is an empty string', () => {
+      const schema: Schema = { API_KEY: { type: 'string', required: true } };
+      expect(() => validate_env({ API_KEY: '' }, schema)).toThrow(
+        'Missing required env var: API_KEY'
+      );
+    });
+
+    it('throws when a required var is null', () => {
+      const schema: Schema = { API_KEY: { type: 'string', required: true } };
+      expect(() => validate_env({ API_KEY: null }, schema)).toThrow(
+        'Missing required env var: API_KEY'
+      );
+    });
+
+    it('does not throw when a required var is present', () => {
+      const schema: Schema = { API_KEY: { type: 'string', required: true } };
+      expect(() => validate_env({ API_KEY: 'my-key' }, schema)).not.toThrow();
+    });
+
+    it('does not throw when an optional var is missing', () => {
+      const schema: Schema = { DEBUG: { type: 'boolean', required: false } };
+      expect(() => validate_env({}, schema)).not.toThrow();
+    });
+
+    it('does not throw when required is not specified and var is missing', () => {
+      const schema: Schema = { DEBUG: { type: 'boolean' } };
+      expect(() => validate_env({}, schema)).not.toThrow();
+    });
+  });
+
+  describe('type validation', () => {
+    describe('number', () => {
+      it('accepts valid number strings', () => {
+        const schema: Schema = { TIMEOUT: { type: 'number' } };
+        expect(() => validate_env({ TIMEOUT: '3000' }, schema)).not.toThrow();
+        expect(() => validate_env({ TIMEOUT: '0' }, schema)).not.toThrow();
+        expect(() => validate_env({ TIMEOUT: '-1' }, schema)).not.toThrow();
+        expect(() => validate_env({ TIMEOUT: '3.14' }, schema)).not.toThrow();
+      });
+
+      it('throws for non-numeric strings', () => {
+        const schema: Schema = { TIMEOUT: { type: 'number' } };
+        expect(() => validate_env({ TIMEOUT: 'fast' }, schema)).toThrow(
+          'TIMEOUT must be a number, got "fast"'
+        );
+        expect(() => validate_env({ TIMEOUT: 'abc' }, schema)).toThrow(
+          'TIMEOUT must be a number'
+        );
+      });
+
+      it('accepts actual number values', () => {
+        const schema: Schema = { TIMEOUT: { type: 'number' } };
+        expect(() => validate_env({ TIMEOUT: 3000 }, schema)).not.toThrow();
+      });
+    });
+
+    describe('boolean', () => {
+      it('accepts valid boolean strings', () => {
+        const schema: Schema = { DEBUG: { type: 'boolean' } };
+        for (const v of ['true', 'false', '1', '0', 'TRUE', 'FALSE']) {
+          expect(() => validate_env({ DEBUG: v }, schema)).not.toThrow();
+        }
+      });
+
+      it('throws for invalid boolean strings', () => {
+        const schema: Schema = { DEBUG: { type: 'boolean' } };
+        expect(() => validate_env({ DEBUG: 'yes' }, schema)).toThrow(
+          'DEBUG must be a boolean (true/false/1/0), got "yes"'
+        );
+        expect(() => validate_env({ DEBUG: 'enabled' }, schema)).toThrow(
+          'DEBUG must be a boolean'
+        );
+      });
+    });
+
+    describe('string', () => {
+      it('accepts any non-empty value as string', () => {
+        const schema: Schema = { NAME: { type: 'string' } };
+        expect(() => validate_env({ NAME: 'hello' }, schema)).not.toThrow();
+        expect(() => validate_env({ NAME: '123' }, schema)).not.toThrow();
+        expect(() => validate_env({ NAME: 'true' }, schema)).not.toThrow();
+      });
+    });
+  });
+
+  describe('pattern validation', () => {
+    it('accepts values matching the pattern', () => {
+      const schema: Schema = {
+        ENV: { type: 'string', pattern: '^(dev|staging|prod)$' },
+      };
+      expect(() => validate_env({ ENV: 'dev' }, schema)).not.toThrow();
+      expect(() => validate_env({ ENV: 'staging' }, schema)).not.toThrow();
+      expect(() => validate_env({ ENV: 'prod' }, schema)).not.toThrow();
+    });
+
+    it('throws for values not matching the pattern', () => {
+      const schema: Schema = {
+        ENV: { type: 'string', pattern: '^(dev|staging|prod)$' },
+      };
+      expect(() => validate_env({ ENV: 'production' }, schema)).toThrow(
+        'ENV does not match pattern /^(dev|staging|prod)$/, got "production"'
+      );
+    });
+
+    it('pattern validation is skipped for missing optional vars', () => {
+      const schema: Schema = {
+        ENV: { type: 'string', pattern: '^(dev|staging|prod)$' },
+      };
+      expect(() => validate_env({}, schema)).not.toThrow();
+    });
+  });
+
+  describe('multiple errors', () => {
+    it('reports all validation errors at once, not just the first', () => {
+      const schema: Schema = {
+        API_KEY: { type: 'string', required: true },
+        TIMEOUT: { type: 'number', required: true },
+        ENV: { type: 'string', pattern: '^(dev|staging|prod)$' },
+      };
+      let error: Error | undefined;
+      try {
+        validate_env({ TIMEOUT: 'fast', ENV: 'production' }, schema);
+      } catch (e) {
+        error = e as Error;
+      }
+      expect(error).toBeDefined();
+      expect(error?.message).toContain('Missing required env var: API_KEY');
+      expect(error?.message).toContain('TIMEOUT must be a number');
+      expect(error?.message).toContain('ENV does not match pattern');
+    });
+  });
+
+  describe('does not throw for valid env', () => {
+    it('passes a complete valid env without error', () => {
+      const schema: Schema = {
+        API_KEY: { type: 'string', required: true },
+        TIMEOUT_MS: { type: 'number', required: true },
+        DEBUG: { type: 'boolean', required: false },
+        ENV_NAME: { type: 'string', required: true, pattern: '^(dev|staging|prod)$' },
+      };
+      expect(() =>
+        validate_env(
+          {
+            API_KEY: 'secret-key',
+            TIMEOUT_MS: '5000',
+            ENV_NAME: 'staging',
+            // DEBUG intentionally omitted (optional)
+          },
+          schema
+        )
+      ).not.toThrow();
+    });
+  });
+});

package/src/validate-env.ts

@@ -0,0 +1,68 @@
+import type { EnvData, Schema } from './resolve-env';
+
+/**
+ * Validate env data against a schema defined in `.rncurc.js`.
+ * Called after `on_env` so the hook can add/transform vars before validation.
+ *
+ * Throws with a human-readable error listing ALL failures at once
+ * (not just the first one), so users can fix everything in one pass.
+ */
+export function validate_env(env: EnvData, schema: Schema): void {
+  const errors: string[] = [];
+
+  // Pre-compile all regex patterns once, before iterating over env values.
+  // This avoids re-compiling the same pattern for every validated key.
+  const compiled_patterns = new Map<string, RegExp>();
+  for (const [key, field] of Object.entries(schema)) {
+    if (field.pattern) {
+      try {
+        compiled_patterns.set(key, new RegExp(field.pattern));
+      } catch {
+        errors.push(`${key}: invalid regex pattern /${field.pattern}/`);
+      }
+    }
+  }
+
+  for (const [key, field] of Object.entries(schema)) {
+    const raw = env[key];
+    const missing =
+      raw === undefined || raw === null || String(raw).trim() === '';
+
+    if (field.required && missing) {
+      errors.push(`Missing required env var: ${key}`);
+      continue; // can't type-check a missing value
+    }
+
+    if (missing) continue; // optional and not present → OK
+
+    const value = String(raw);
+
+    if (field.type === 'number' && isNaN(Number(value))) {
+      errors.push(`${key} must be a number, got "${value}"`);
+    }
+
+    if (
+      field.type === 'boolean' &&
+      !['true', 'false', '1', '0'].includes(value.toLowerCase())
+    ) {
+      errors.push(
+        `${key} must be a boolean (true/false/1/0), got "${value}"`
+      );
+    }
+
+    const pattern = compiled_patterns.get(key);
+    if (pattern && !pattern.test(value)) {
+      errors.push(
+        `${key} does not match pattern /${field.pattern}/, got "${value}"`
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(
+      `\n\n❌ react-native-config-ultimate: env validation failed:\n` +
+        errors.map((e) => `  • ${e}`).join('\n') +
+        '\n'
+    );
+  }
+}

package/src/write-env.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = write_env;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Atomically write all generated files.
+ *
+ * Strategy: write each file to a temp path first, then rename (atomic on POSIX).
+ * If any write fails, we abort before committing any renames so the project
+ * is never left in a partially-written state.
+ *
+ * On Windows, `fs.renameSync` across drives may fail — in that case we fall
+ * back to a direct `writeFileSync` (best-effort, still better than nothing).
+ */
+function write_env(files) {
+    const tmp_dir = os.tmpdir();
+    // Phase 1: write all content to temp files — if anything fails, no real files are touched.
+    const pending = [];
+    try {
+        for (const dest of Object.keys(files)) {
+            // Ensure the destination directory exists (handles first-run and hoisted workspaces).
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            const tmp = path.join(tmp_dir, `rncu_${Date.now()}_${Math.random().toString(36).slice(2)}`);
+            fs.writeFileSync(tmp, files[dest], 'utf8');
+            pending.push({ tmp, dest });
+        }
+    }
+    catch (err) {
+        // Clean up any temp files we already created.
+        for (const { tmp } of pending) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch ( /* ignore */_a) { /* ignore */ }
+        }
+        throw new Error(`[rncu] Failed to prepare output files: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Phase 2: atomically rename temp → dest.
+    // We collect errors and rethrow at the end so the caller gets a clear message.
+    const rename_errors = [];
+    for (const { tmp, dest } of pending) {
+        try {
+            fs.renameSync(tmp, dest);
+        }
+        catch (_b) {
+            // Cross-device rename (e.g. Windows different drives) — fall back to copy+delete.
+            try {
+                fs.copyFileSync(tmp, dest);
+                fs.unlinkSync(tmp);
+            }
+            catch (copy_err) {
+                rename_errors.push(`${dest}: ${copy_err instanceof Error ? copy_err.message : String(copy_err)}`);
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch ( /* ignore */_c) { /* ignore */ }
+            }
+        }
+    }
+    if (rename_errors.length > 0) {
+        throw new Error(`[rncu] Failed to write output files:\n` +
+            rename_errors.map((e) => `  • ${e}`).join('\n'));
+    }
+}