ngx-api-forms 1.0.0

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "ngx-api-forms",
+  "version": "1.0.0",
+  "description": "Bridge API validation errors to Angular Reactive Forms. Supports NestJS/class-validator, Zod, Laravel, Django REST, express-validator and custom presets.",
+  "keywords": [
+    "angular",
+    "forms",
+    "api",
+    "validation",
+    "error-handling",
+    "nestjs",
+    "class-validator",
+    "reactive-forms",
+    "form-helper",
+    "ng",
+    "ngx",
+    "i18n",
+    "ssr",
+    "zod",
+    "laravel",
+    "django",
+    "express",
+    "express-validator",
+    "angular-validation-errors",
+    "422",
+    "server-side-validation",
+    "form-errors",
+    "http-interceptor"
+  ],
+  "author": {
+    "name": "Mikhaël GERBET",
+    "email": "frollon.noir@gmail.com",
+    "url": "https://github.com/MikhaelGerbet"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MikhaelGerbet/ngx-api-forms.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MikhaelGerbet/ngx-api-forms/issues"
+  },
+  "homepage": "https://github.com/MikhaelGerbet/ngx-api-forms#readme",
+  "peerDependencies": {
+    "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
+    "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
+    "@angular/forms": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "schematics": "./schematics/collection.json",
+  "sideEffects": false,
+  "module": "fesm2022/ngx-api-forms.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/ngx-api-forms.mjs"
+    },
+    "./analog": {
+      "types": "./analog/index.d.ts",
+      "default": "./fesm2022/ngx-api-forms-analog.mjs"
+    },
+    "./django": {
+      "types": "./django/index.d.ts",
+      "default": "./fesm2022/ngx-api-forms-django.mjs"
+    },
+    "./express-validator": {
+      "types": "./express-validator/index.d.ts",
+      "default": "./fesm2022/ngx-api-forms-express-validator.mjs"
+    },
+    "./laravel": {
+      "types": "./laravel/index.d.ts",
+      "default": "./fesm2022/ngx-api-forms-laravel.mjs"
+    },
+    "./zod": {
+      "types": "./zod/index.d.ts",
+      "default": "./fesm2022/ngx-api-forms-zod.mjs"
+    }
+  }
+}

package/schematics/collection.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add ngx-api-forms to the project",
+      "factory": "./ng-add/index#ngAdd",
+      "schema": "./ng-add/schema.json"
+    }
+  }
+}

package/schematics/ng-add/index.js

@@ -0,0 +1,300 @@
+"use strict";
+
+const schematics = require("@angular-devkit/schematics");
+const tasks = require("@angular-devkit/schematics/tasks");
+
+/**
+ * Maps preset names to their import configuration.
+ * class-validator lives in the primary entry point; all others are secondary.
+ */
+const PRESET_CONFIG = {
+  "class-validator": {
+    importName: "classValidatorPreset",
+    importPath: "ngx-api-forms",
+    call: "classValidatorPreset()",
+  },
+  laravel: {
+    importName: "laravelPreset",
+    importPath: "ngx-api-forms/laravel",
+    call: "laravelPreset()",
+  },
+  django: {
+    importName: "djangoPreset",
+    importPath: "ngx-api-forms/django",
+    call: "djangoPreset()",
+  },
+  zod: {
+    importName: "zodPreset",
+    importPath: "ngx-api-forms/zod",
+    call: "zodPreset()",
+  },
+  "express-validator": {
+    importName: "expressValidatorPreset",
+    importPath: "ngx-api-forms/express-validator",
+    call: "expressValidatorPreset()",
+  },
+  analog: {
+    importName: "analogPreset",
+    importPath: "ngx-api-forms/analog",
+    call: "analogPreset()",
+  },
+};
+
+function ngAdd(options) {
+  return (tree, context) => {
+    context.addTask(new tasks.NodePackageInstallTask());
+
+    const preset = options.preset || "class-validator";
+    const config = PRESET_CONFIG[preset] || PRESET_CONFIG["class-validator"];
+
+    // 1. Create example component
+    const examplePath = "src/app/api-forms-example.component.ts";
+    if (!tree.exists(examplePath)) {
+      tree.create(examplePath, buildExampleContent(config));
+      context.logger.info(
+        "Created " + examplePath + " with " + preset + " preset."
+      );
+    } else {
+      context.logger.warn(
+        examplePath + " already exists. Skipping example generation."
+      );
+    }
+
+    // 2. Auto-inject interceptor into app.config.ts
+    const appConfigPath = "src/app/app.config.ts";
+    if (tree.exists(appConfigPath)) {
+      const content = tree.read(appConfigPath).toString("utf-8");
+      const updated = injectInterceptor(content);
+      if (updated !== content) {
+        tree.overwrite(appConfigPath, updated);
+        context.logger.info(
+          "Updated " + appConfigPath + ": added apiErrorInterceptor to HttpClient interceptors."
+        );
+      } else if (content.includes("apiErrorInterceptor")) {
+        context.logger.info(
+          appConfigPath + " already contains apiErrorInterceptor. Skipping."
+        );
+      } else {
+        context.logger.warn(
+          "Could not auto-inject interceptor into " + appConfigPath + ".\n" +
+          "Add it manually:\n\n" +
+          "  import { provideHttpClient, withInterceptors } from '@angular/common/http';\n" +
+          "  import { apiErrorInterceptor } from 'ngx-api-forms';\n\n" +
+          "  provideHttpClient(withInterceptors([apiErrorInterceptor()]))\n"
+        );
+      }
+    } else {
+      context.logger.warn(
+        "Could not find " + appConfigPath + ". Add the interceptor manually:\n\n" +
+        "  import { provideHttpClient, withInterceptors } from '@angular/common/http';\n" +
+        "  import { apiErrorInterceptor } from 'ngx-api-forms';\n\n" +
+        "  provideHttpClient(withInterceptors([apiErrorInterceptor()]))\n"
+      );
+    }
+
+    return tree;
+  };
+}
+
+/**
+ * Attempts to inject `apiErrorInterceptor()` into an app.config.ts file.
+ * Returns the modified content, or the original if injection was not possible.
+ *
+ * Handles three cases:
+ * 1. `withInterceptors([...])` exists -> add apiErrorInterceptor() to the array
+ * 2. `provideHttpClient(...)` exists without withInterceptors -> add withInterceptors
+ * 3. Neither exists -> add provideHttpClient with interceptor to providers array
+ */
+function injectInterceptor(content) {
+  // Already present
+  if (content.includes("apiErrorInterceptor")) return content;
+
+  let result = content;
+
+  // Ensure apiErrorInterceptor import exists
+  // Check if there's already an import from 'ngx-api-forms'
+  const ngxImportRegex = /import\s*\{([^}]+)\}\s*from\s*['"]ngx-api-forms['"]/;
+  const ngxImportMatch = result.match(ngxImportRegex);
+  if (ngxImportMatch) {
+    // Add to existing import (trim to avoid double spaces)
+    const existingImports = ngxImportMatch[1].trim();
+    result = result.replace(
+      ngxImportMatch[0],
+      "import { " + existingImports + ", apiErrorInterceptor } from 'ngx-api-forms'"
+    );
+  } else {
+    // Add new import after last import line
+    const lastImportIndex = result.lastIndexOf("import ");
+    if (lastImportIndex !== -1) {
+      const afterImport = result.substring(lastImportIndex);
+      const semiIndex = afterImport.indexOf(";");
+      if (semiIndex !== -1) {
+        const importEnd = lastImportIndex + semiIndex + 1;
+        result =
+          result.substring(0, importEnd) +
+          "\nimport { apiErrorInterceptor } from 'ngx-api-forms';" +
+          result.substring(importEnd);
+      }
+    }
+  }
+
+  // Case 1: withInterceptors([...]) exists -> add to array
+  const withInterceptorsRegex = /withInterceptors\s*\(\s*\[([^\]]*)\]/;
+  const withInterceptorsMatch = result.match(withInterceptorsRegex);
+  if (withInterceptorsMatch) {
+    const existingInterceptors = withInterceptorsMatch[1].trim();
+    const separator = existingInterceptors.length > 0 ? ", " : "";
+    result = result.replace(
+      withInterceptorsMatch[0],
+      "withInterceptors([" + existingInterceptors + separator + "apiErrorInterceptor()]"
+    );
+    result = ensureHttpImport(result, "withInterceptors");
+    return result;
+  }
+
+  // Case 2: provideHttpClient(...) exists without withInterceptors
+  // Use balanced-paren scanner to handle nested calls like withFetch()
+  const phcIndex = result.indexOf("provideHttpClient(");
+  if (phcIndex !== -1) {
+    const openParen = phcIndex + "provideHttpClient".length;
+    let depth = 0;
+    let closeParen = -1;
+    for (let i = openParen; i < result.length; i++) {
+      if (result[i] === "(") depth++;
+      else if (result[i] === ")") {
+        depth--;
+        if (depth === 0) { closeParen = i; break; }
+      }
+    }
+    if (closeParen !== -1) {
+      const existingArgs = result.substring(openParen + 1, closeParen).trim();
+      const separator = existingArgs.length > 0 ? ", " : "";
+      result =
+        result.substring(0, openParen + 1) +
+        existingArgs + separator + "withInterceptors([apiErrorInterceptor()])" +
+        result.substring(closeParen);
+      result = ensureHttpImport(result, "provideHttpClient");
+      result = ensureHttpImport(result, "withInterceptors");
+      return result;
+    }
+  }
+
+  // Case 3: No provideHttpClient -> add to providers array
+  const providersRegex = /providers\s*:\s*\[/;
+  const providersMatch = result.match(providersRegex);
+  if (providersMatch) {
+    result = result.replace(
+      providersMatch[0],
+      providersMatch[0] +
+        "\n    provideHttpClient(withInterceptors([apiErrorInterceptor()])),"
+    );
+    result = ensureHttpImport(result, "provideHttpClient");
+    result = ensureHttpImport(result, "withInterceptors");
+    return result;
+  }
+
+  // Could not inject
+  return content;
+}
+
+/**
+ * Ensures a symbol is imported from '@angular/common/http'.
+ * Only checks import statements, not usage in code.
+ */
+function ensureHttpImport(content, symbol) {
+  const httpImportRegex = /import\s*\{([^}]+)\}\s*from\s*['"]@angular\/common\/http['"]/;
+  const match = content.match(httpImportRegex);
+
+  if (match) {
+    // Already imported?
+    if (match[1].includes(symbol)) return content;
+    // Add to existing import
+    return content.replace(
+      match[0],
+      "import { " + match[1].trim() + ", " + symbol + " } from '@angular/common/http'"
+    );
+  }
+
+  // Add new import after last import
+  const lastImportIndex = content.lastIndexOf("import ");
+  if (lastImportIndex !== -1) {
+    const afterImport = content.substring(lastImportIndex);
+    const semiIndex = afterImport.indexOf(";");
+    if (semiIndex !== -1) {
+      const importEnd = lastImportIndex + semiIndex + 1;
+      return (
+        content.substring(0, importEnd) +
+        "\nimport { " + symbol + " } from '@angular/common/http';" +
+        content.substring(importEnd)
+      );
+    }
+  }
+  return content;
+}
+
+function buildExampleContent(config) {
+  const presetImportLine =
+    config.importPath === "ngx-api-forms"
+      ? "import {\n" +
+        "  provideFormBridge,\n" +
+        "  " + config.importName + ",\n" +
+        "  NgxFormErrorDirective,\n" +
+        "} from 'ngx-api-forms';\n"
+      : "import { provideFormBridge, NgxFormErrorDirective } from 'ngx-api-forms';\n" +
+        "import { " + config.importName + " } from '" + config.importPath + "';\n";
+
+  return (
+    "import { Component, inject } from '@angular/core';\n" +
+    "import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';\n" +
+    "import { HttpClient } from '@angular/common/http';\n" +
+    presetImportLine +
+    "\n" +
+    "@Component({\n" +
+    "  selector: 'app-api-forms-example',\n" +
+    "  standalone: true,\n" +
+    "  imports: [ReactiveFormsModule, NgxFormErrorDirective],\n" +
+    "  template: `\n" +
+    "    <form [formGroup]=\"form\" (ngSubmit)=\"onSubmit()\">\n" +
+    "      <label>\n" +
+    "        Email\n" +
+    "        <input formControlName=\"email\" />\n" +
+    "        <span ngxFormError=\"email\" [form]=\"form\"></span>\n" +
+    "      </label>\n" +
+    "\n" +
+    "      <label>\n" +
+    "        Name\n" +
+    "        <input formControlName=\"name\" />\n" +
+    "        <span ngxFormError=\"name\" [form]=\"form\"></span>\n" +
+    "      </label>\n" +
+    "\n" +
+    "      <button type=\"submit\">Save</button>\n" +
+    "    </form>\n" +
+    "  `,\n" +
+    "})\n" +
+    "export class ApiFormsExampleComponent {\n" +
+    "  private http = inject(HttpClient);\n" +
+    "  private fb = inject(FormBuilder);\n" +
+    "\n" +
+    "  form = this.fb.group({\n" +
+    "    email: ['', [Validators.required, Validators.email]],\n" +
+    "    name: ['', [Validators.required, Validators.minLength(3)]],\n" +
+    "  });\n" +
+    "\n" +
+    "  bridge = provideFormBridge(this.form, {\n" +
+    "    preset: " + config.call + ",\n" +
+    "  });\n" +
+    "\n" +
+    "  onSubmit() {\n" +
+    "    if (this.form.invalid) return;\n" +
+    "\n" +
+    "    this.http.post('/api/example', this.form.value).subscribe({\n" +
+    "      next: () => console.log('Success'),\n" +
+    "      error: (err) => this.bridge.applyApiErrors(err.error),\n" +
+    "    });\n" +
+    "  }\n" +
+    "}\n"
+  );
+}
+
+exports.ngAdd = ngAdd;
+exports.injectInterceptor = injectInterceptor;

package/schematics/ng-add/index.spec.js

@@ -0,0 +1,119 @@
+// Node.js test for ng-add schematic (injectInterceptor)
+// Run: node --test projects/ngx-api-forms/schematics/ng-add/index.spec.js
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { injectInterceptor } = require('./index');
+
+describe('injectInterceptor', () => {
+  it('should add interceptor to existing withInterceptors array', () => {
+    const input = [
+      "import { provideHttpClient, withInterceptors } from '@angular/common/http';",
+      '',
+      'export const appConfig = {',
+      '  providers: [',
+      '    provideHttpClient(withInterceptors([myInterceptor]))',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.ok(result.includes('apiErrorInterceptor()'));
+    assert.ok(result.includes('myInterceptor, apiErrorInterceptor()'));
+  });
+
+  it('should add withInterceptors to bare provideHttpClient()', () => {
+    const input = [
+      "import { provideHttpClient } from '@angular/common/http';",
+      '',
+      'export const appConfig = {',
+      '  providers: [',
+      '    provideHttpClient()',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.ok(result.includes('withInterceptors([apiErrorInterceptor()])'));
+    assert.ok(result.includes('provideHttpClient(withInterceptors'));
+  });
+
+  it('should add provideHttpClient when only providers array exists', () => {
+    const input = [
+      "import { ApplicationConfig } from '@angular/core';",
+      '',
+      'export const appConfig: ApplicationConfig = {',
+      '  providers: [',
+      '    provideZonelessChangeDetection(),',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.ok(result.includes('provideHttpClient(withInterceptors([apiErrorInterceptor()]))'));
+    assert.ok(result.includes("import { apiErrorInterceptor } from 'ngx-api-forms'"));
+  });
+
+  it('should not modify if apiErrorInterceptor already present', () => {
+    const input = [
+      "import { apiErrorInterceptor } from 'ngx-api-forms';",
+      "import { provideHttpClient, withInterceptors } from '@angular/common/http';",
+      '',
+      'export const appConfig = {',
+      '  providers: [',
+      '    provideHttpClient(withInterceptors([apiErrorInterceptor()]))',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.equal(result, input);
+  });
+
+  it('should add to existing ngx-api-forms import', () => {
+    const input = [
+      "import { provideFormBridge } from 'ngx-api-forms';",
+      "import { provideHttpClient, withInterceptors } from '@angular/common/http';",
+      '',
+      'export const appConfig = {',
+      '  providers: [',
+      '    provideHttpClient(withInterceptors([]))',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.ok(result.includes('provideFormBridge, apiErrorInterceptor'));
+    assert.ok(result.includes('apiErrorInterceptor()'));
+  });
+
+  it('should handle provideHttpClient with existing args', () => {
+    const input = [
+      "import { provideHttpClient, withFetch } from '@angular/common/http';",
+      '',
+      'export const appConfig = {',
+      '  providers: [',
+      '    provideHttpClient(withFetch())',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.ok(result.includes('provideHttpClient(withFetch(), withInterceptors([apiErrorInterceptor()]))'));
+  });
+
+  it('should add HTTP imports when missing', () => {
+    const input = [
+      "import { ApplicationConfig } from '@angular/core';",
+      '',
+      'export const appConfig: ApplicationConfig = {',
+      '  providers: [',
+      '    provideZonelessChangeDetection(),',
+      '  ]',
+      '};',
+    ].join('\n');
+
+    const result = injectInterceptor(input);
+    assert.ok(result.includes("import { provideHttpClient, withInterceptors } from '@angular/common/http'"));
+  });
+});

package/schematics/ng-add/schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "id": "ngx-api-forms-ng-add",
+  "title": "Add ngx-api-forms",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project to add ngx-api-forms to.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "preset": {
+      "type": "string",
+      "description": "The backend preset to generate.",
+      "default": "class-validator",
+      "enum": ["laravel", "django", "class-validator", "zod", "express-validator", "analog"],
+      "x-prompt": {
+        "message": "Which backend preset do you want to use?",
+        "type": "list",
+        "items": [
+          { "value": "class-validator", "label": "NestJS / class-validator" },
+          { "value": "laravel", "label": "Laravel" },
+          { "value": "django", "label": "Django REST Framework" },
+          { "value": "express-validator", "label": "Express / express-validator" },
+          { "value": "zod", "label": "Zod (tRPC, Remix, etc.)" },
+          { "value": "analog", "label": "Analog (Nitro/h3 backend)" }
+        ]
+      }
+    }
+  },
+  "required": []
+}

package/zod/index.d.ts

@@ -0,0 +1,58 @@
+import { ErrorPreset, ConstraintMap } from 'ngx-api-forms';
+
+/**
+ * Zod error preset.
+ *
+ * Parses errors from `ZodError.flatten()`:
+ * ```json
+ * {
+ *   "formErrors": [],
+ *   "fieldErrors": {
+ *     "email": ["Invalid email"],
+ *     "name": ["String must contain at least 3 character(s)"]
+ *   }
+ * }
+ * ```
+ *
+ * Also supports raw `ZodError.issues`:
+ * ```json
+ * [
+ *   { "code": "too_small", "minimum": 3, "path": ["name"], "message": "..." },
+ *   { "code": "invalid_string", "validation": "email", "path": ["email"], "message": "..." }
+ * ]
+ * ```
+ */
+
+/**
+ * Default constraint map for Zod.
+ */
+declare const ZOD_CONSTRAINT_MAP: ConstraintMap;
+/**
+ * Creates a Zod error preset.
+ *
+ * Supports both `.flatten()` and raw `.issues` formats.
+ *
+ * @param options.noInference - When true, skips constraint guessing entirely.
+ *   The raw error message is used directly and the constraint is set to `'serverError'`.
+ *   Useful for custom or translated Zod error messages.
+ * @param options.constraintPatterns - Custom regex patterns for constraint inference.
+ *   Keys are constraint names, values are RegExp tested against the raw message.
+ *   Checked before the built-in English patterns (flattened format only;
+ *   the raw issues format uses structured `code` fields which are language-independent).
+ *
+ * @example
+ * ```typescript
+ * import { zodPreset } from 'ngx-api-forms/zod';
+ *
+ * const bridge = createFormBridge(form, { preset: zodPreset() });
+ *
+ * // No inference: raw messages, no guessing
+ * const bridge = createFormBridge(form, { preset: zodPreset({ noInference: true }) });
+ * ```
+ */
+declare function zodPreset(options?: {
+    noInference?: boolean;
+    constraintPatterns?: Record<string, RegExp>;
+}): ErrorPreset;
+
+export { ZOD_CONSTRAINT_MAP, zodPreset };