Continue implementing OpenAPI 3.2.0 ; [FUTURE.md] Rewrite with new roadmap, with properly constituted next steps and potential next steps

Author: SamuelMarks

FUTURE.md

@@ -1,18 +1,48 @@
-### Roadmap & Feature Compliance
-
-This project already implements a vast and powerful set of features from the OpenAPI specification, focusing on the most common use cases for modern Angular applications. The table below outlines features from the standard that are not yet implemented, ordered by priority. This can serve as a roadmap for future development.
-
-| Priority                                   | Feature                                                                          | Description & Justification                                                                                                                                                                                                                                                              |
-| :----------------------------------------- | :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🚀 **High**                                  | Multi-Document Support (`$ref` to external files)                                | **What:** Allow `$ref` to point to external local or remote files (e.g., `./schemas/User.yaml`). <br/> **Why:** This is crucial for large, real-world APIs where the specification is split across multiple files for maintainability. Implementing this would dramatically increase the generator's utility for enterprise-scale projects. |
-| 🚀 **High**                                  | Server Configuration (`servers` array & `variables`)                             | **What:** Support for the top-level `servers` array, including URL variables for templating hosts, ports, or base paths. <br/> **Why:** This is the standard way to define different environments (dev, staging, prod) and is more flexible than a single `basePath` injection token. |
-| 🚀 **High**                                  | Advanced Parameter Serialization (`style`/`explode`)                             | **What:** Fully support the `style` and `explode` keywords on `Parameter Object`s to control how arrays and objects are formatted in query strings and paths. <br/> **Why:** Correctly handling common patterns like `?ids=1&ids=2` (`style: 'form', explode: true`) is a fundamental part of spec compliance. |
-| 🚀 **High**                                  | Support for Other Media Types (`application/x-www-form-urlencoded`, `multipart/form-data`) | **What:** Parse schemas for common media types beyond `application/json`. <br/> **Why:** Many APIs use `x-www-form-urlencoded` for simple forms (like OAuth) and `multipart/form-data` for file uploads with associated metadata. This would make the generator much more versatile. |
-| 🚀 **High**                                  | Modern Binary Data Representation (`contentMediaType`/`contentEncoding`)         | **What:** Support the OpenAPI 3.1+ approach to defining binary data using JSON Schema's `contentMediaType` and `contentEncoding`. <br/> **Why:** While your current `format: 'binary'` works for OAS 3.0, adopting the modern standard ensures future-proofing and better spec alignment. |
-| 🔧 **Medium**                                | Links & Hypermedia (`Link Object`)                                               | **What:** Parse the `links` object in responses to understand HATEOAS relationships between operations. <br/> **Why:** This would enable the generation of "smarter" client libraries with helper methods on models to navigate the API, elevating the developer experience. |
-| 🔧 **Medium**                                | Expanded Security Schemes (`openIdConnect`)                                      | **What:** Add support for the `openIdConnect` security scheme, which includes a `openIdConnectUrl` for auto-discovery. <br/> **Why:** This is a natural and valuable extension of your existing OAuth2 support, common in modern authentication setups. |
-| 🔧 **Medium**                                | Callbacks (`Callback Object`)                                                    | **What:** Support the `callbacks` field on operations for defining out-of-band, asynchronous responses to an API call. <br/> **Why:** This is essential for APIs with long-running processes or asynchronous workflows where the server calls back to the client. |
-| 🔧 **Medium**                                | Additional `in` Locations (`cookie`, `querystring`)                              | **What:** Handle parameters located `in: "cookie"` or the special `in: "querystring"` which treats the entire query string as a single value. <br/> **Why:** Improves completeness of parameter handling, although these are less common than path, query, and header. |
-| 📚 **Low**                                   | Webhooks (`webhooks` object)                                                     | **What:** Support the top-level `webhooks` field for defining completely out-of-band events sent from the provider to the consumer. <br/> **Why:** This is a different paradigm from a client library making requests. It's a large feature better suited for generating server-side stubs. |
-| 📚 **Low**                                   | XML Modeling (`xml` object)                                                      | **What:** Parse the `xml` object within schemas to understand how a model should be represented as XML. <br/> **Why:** Your generator is clearly focused on the JSON/TypeScript ecosystem. XML support is a very heavy lift for a different data paradigm and is a low priority. |
-| 📚 **Low**                                   | Metadata in `Tag`, `ExternalDocs`, etc.                                          | **What:** Use descriptive metadata from `Tag Object`s or `External Documentation Object`s. <br/> **Why:** This is a "nice-to-have" polishing step to add richer JSDoc comments to the generated services and models, improving developer experience but not affecting runtime. |
+Future
+======
+
+This project could go in multiple directions.
+
+One idea I've been playing with is to focus on interoperability. This is out-of-scope for cdd-web-_ng_ as the _ng_
+stands for Angular… but this repo could be split up into base/`abstract` `class`es whence this repo has the Angular
+specific tech… or even rename this repo and this package handles all Angular and non-Angular solutions (in the
+TypeScript web-frontend framework space).
+
+## Full OpenAPI 3.2.0 + Swagger 2 compatibility
+
+- [ ] Full OpenAPI 3.2.0 + Swagger 2 compatibility
+
+## HTTP client interoperability
+
+Add support for:
+
+- [ ] [Fetch API (builtin)](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+- [ ] [Axios](https://axios-http.com)
+
+## Framework interoperability
+
+Add support for creating an auto-admin UI for/with:
+
+- [ ] [Web components (builtin)](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
+- [ ] [Qwik](https://qwik.dev)
+- [ ] [React](https://react.dev)
+- [ ] [Svelte](https://svelte.dev)
+- [ ] [Vue](https://vuejs.org)
+
+## Sync within codebase
+
+- [ ] Modify mock can update client can update admin UI.
+- [ ] Modify admin UI can update mock can update client.
+
+## FROM codebase TO OpenAPI
+
+- [ ] Bidirectionality is what distinctly makes it _cdd_: **C**ompiler **D**riven **D**evelopment.
+
+## CI/CD
+
+GitHub Actions for:
+
+- [ ] tests
+- [ ] linting and other code-quality checks
+- [ ] release to npmjs
+- [ ] release hosted HTML API docs

src/core/parser.ts

@@ -89,7 +89,7 @@ export class SwaggerParser {
     /** A normalized record of all reusable links defined in the entry specification. */
     public readonly links: Record<string, LinkObject>;
 
-    /** A cache of all loaded specifications, keyed by their absolute URI. */
+    /** A cache of all loaded specifications (and sub-schemas with $id), keyed by their absolute URI. */
     private readonly specCache: Map<string, SwaggerSpec>;
 
     /**
@@ -132,6 +132,11 @@ export class SwaggerParser {
         // If a cache isn't provided, create one with just the entry spec.
         this.specCache = specCache || new Map<string, SwaggerSpec>([[this.documentUri, spec]]);
 
+        // Ensure the entry spec's internal $ids are indexed if constructed manually without the factory
+        if (!specCache) {
+            SwaggerParser.indexSchemaIds(spec, documentUri, this.specCache);
+        }
+
         this.schemas = Object.entries(this.getDefinitions()).map(([name, definition]) => ({
             name: pascalCase(name),
             definition
@@ -172,7 +177,8 @@ export class SwaggerParser {
      * @private
      */
     private static async loadAndCacheSpecRecursive(uri: string, cache: Map<string, SwaggerSpec>, visited: Set<string>): Promise<void> {
-        if (visited.has(uri)) return;
+        // If we've visited this URI, or it's already in cache (possibly explicitly added via $id index), skip.
+        if (visited.has(uri) || cache.has(uri)) return;
         visited.add(uri);
 
         const content = await this.loadContent(uri);
@@ -181,16 +187,74 @@ export class SwaggerParser {
 
         const baseUri = spec.$self ? new URL(spec.$self, uri).href : uri;
 
+        // Important: Index any `$id` properties within the document immediately.
+        // This allows internal sub-schemas to be referenced by their global URI (OAS 3.1 / JSON Schema).
+        this.indexSchemaIds(spec, baseUri, cache);
+
         const refs = this.findRefs(spec);
         for (const ref of refs) {
             const [filePath] = ref.split('#', 2);
-            if (filePath) { // It's a reference to another document
-                const nextUri = new URL(filePath, baseUri).href;
-                await this.loadAndCacheSpecRecursive(nextUri, cache, visited);
+            if (filePath) { // It's a reference to another document or an absolute URI ID
+                try {
+                    const nextUri = new URL(filePath, baseUri).href;
+                    await this.loadAndCacheSpecRecursive(nextUri, cache, visited);
+                } catch (e) {
+                    console.warn(`[Parser] Failed to resolve referenced URI: ${filePath}. Skipping.`);
+                }
             }
         }
     }
 
+    /**
+     * Traverses a document structure to find JSON Schema `$id` keywords.
+     * Maps the resolved absolute URI of the ID to the schema configuration object in the cache.
+     * This creates "virtual" documents in the cache, supporting `$ref` resolution by ID.
+     *
+     * @param spec The document root or fragment to traverse.
+     * @param baseUri The current base URI of the scope.
+     * @param cache The specification cache.
+     * @private
+     */
+    private static indexSchemaIds(spec: any, baseUri: string, cache: Map<string, SwaggerSpec>) {
+        if (!spec || typeof spec !== 'object') return;
+
+        // Helper function to recursively traverse and update base URI context
+        const traverse = (obj: any, currentBase: string, visited: Set<any>) => {
+            if (!obj || typeof obj !== 'object' || visited.has(obj)) return;
+            visited.add(obj);
+
+            let nextBase = currentBase;
+
+            // Check for $id (OAS 3.1 / JSON Schema definition)
+            if ('$id' in obj && typeof obj.$id === 'string') {
+                try {
+                    // Resolve $id against the current base.
+                    // $id can be relative or absolute.
+                    // If absolute, it resets the base.
+                    nextBase = new URL(obj.$id, currentBase).href;
+
+                    // Cache this object as a distinct "document" at this URI
+                    // We use cast because cache expects SwaggerSpec, but these are Schema definitions.
+                    // Our resolution logic handles both.
+                    if (!cache.has(nextBase)) {
+                        cache.set(nextBase, obj as SwaggerSpec);
+                    }
+                } catch (e) {
+                    // Ignore invalid $id values
+                }
+            }
+
+            // Recurse into children
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    traverse(obj[key], nextBase, visited);
+                }
+            }
+        };
+
+        traverse(spec, baseUri, new Set());
+    }
+
     /**
      * Recursively finds all unique `$ref` and `$dynamicRef` values within a given object.
      * @param obj The object to search.
@@ -375,17 +439,13 @@ export class SwaggerParser {
         // Get the specification for the current document context to determine its logical base URI.
         const currentDocSpec = this.specCache.get(currentDocUri);
 
-        // This can happen if an invalid URI is somehow passed as the context.
-        if (!currentDocSpec) {
-            console.warn(`[Parser] Unresolved document URI in cache: ${currentDocUri}. Cannot resolve reference "${ref}".`);
-            return undefined;
-        }
-
-        // The base for resolving relative file paths is the document's logical URI, derived from its $self,
-        // falling back to its physical URI.
-        const logicalBaseUri = currentDocSpec.$self ? new URL(currentDocSpec.$self, currentDocUri).href : currentDocUri;
+        // logicalBaseUri calculation: checks $self first, then falls back to current physical URI.
+        // NOTE: For $id resolution, the cache key IS the $id (resolved), so looking up by URI works
+        // naturally if `indexSchemaIds` has populated the cache.
+        const logicalBaseUri = currentDocSpec?.$self ? new URL(currentDocSpec.$self, currentDocUri).href : currentDocUri;
 
-        // The target file's physical URI is resolved using the logical base. If the ref is local, it's just the current doc's physical URI.
+        // The target file's physical URI is resolved using the logical base.
+        // If ref is absolute (e.g. based on $id), URL construction handles it correctly.
         const targetFileUri = filePath ? new URL(filePath, logicalBaseUri).href : currentDocUri;
 
         const targetSpec = this.specCache.get(targetFileUri);

src/core/types.ts

@@ -528,6 +528,11 @@ export interface SwaggerSpec {
 export interface GeneratorConfigOptions {
     /** The TypeScript type to use for properties with `format: "date"` or `"date-time"`. */
     dateType?: 'string' | 'Date';
+    /**
+     * The TypeScript type to use for `integer` types with `format: "int64"`.
+     * Default is 'number', but 'string' is often safer for browser JS due to precision limit (2^53).
+     */
+    int64Type?: 'number' | 'string' | 'bigint';
     /** How to generate types for schemas with an `enum` list. */
     enumStyle?: 'enum' | 'union';
     /** If true, generates Angular services for API operations. */
@@ -540,6 +545,12 @@ export interface GeneratorConfigOptions {
     generateAdminTests?: boolean;
     /** A record of static headers to be added to every generated service request. */
     customHeaders?: Record<string, string>;
+    /**
+     * Target runtime platform for the generated code.
+     * - 'browser': (Default) Assumes standard browser environment. Cookie setting in headers will emit warnings.
+     * - 'node': Assumes Node.js/SSR environment. Cookie setting is allowed without warnings.
+     */
+    platform?: 'browser' | 'node';
     /** A callback to provide a custom method name for an operation. */
     customizeMethodName?: ((operationId: string) => string);
 }

src/core/utils.ts

@@ -233,9 +233,19 @@ export function getTypeScriptType(schema: SwaggerDefinition | undefined | null,
             }
             break;
         case 'number':
-        case 'integer':
             type = 'number';
             break;
+        case 'integer':
+            // Enhanced support for OAS 3.2 / Data Types strict format mapping requirement.
+            // While 'number' is the standard JS type for all integers, large integers (int64)
+            // can encounter precision loss in JS (> 2^53).
+            // We now support a configuration option to map `int64` to `string` or `bigint`.
+            if (schema.format === 'int64') {
+                type = config.options.int64Type ?? 'number';
+            } else {
+                type = 'number'; // Default for int32 and others
+            }
+            break;
         case 'boolean':
             type = 'boolean';
             break;
@@ -313,7 +323,7 @@ export function getTypeScriptType(schema: SwaggerDefinition | undefined | null,
  * @returns `true` if the type is likely a generated model interface, `false` otherwise.
  */
 export function isDataTypeInterface(type: string): boolean {
-    const primitiveOrBuiltIn = /^(any|File|Blob|string|number|boolean|object|unknown|null|undefined|Date|void)$/;
+    const primitiveOrBuiltIn = /^(any|File|Blob|string|number|boolean|object|unknown|null|undefined|Date|void|bigint)$/;
     const isArray = /\[\]$/;
     const isUnion = / \| /;
     return !primitiveOrBuiltIn.test(type) && !isArray.test(type) && !isUnion.test(type) && !type.startsWith('{') && !type.startsWith('Record');