How to modify existing interfaces

[ballcoach12]

I am writing a system that can be used to query JSON. It will be used in a domain specific language that I am also writing. The syntax is similar to TaffyDB query syntax, and a query essentially specifies a path to a JSON property and a criteria for a value that must be satisfied.

The first step in validating the query syntax is to determine if the specified property path exists or not. In order to do this, I will use a schema that is loaded from an OpenAPI specification. Since the spec is OpenAPI compiant, the structure of the schema object is expected to match that of a SchemaObject in the openapi-typescript types; so when I load the object at runtime, its type should match that of the SchemaObject.

Here is a synopsis of the steps that I'm trying to accomplish:

1. Import the OpenAPI spec that contains the object that is the subject of the query.

   import * as MySpec from './schema.json'

2. Pass the object to a validate() function:

const bob = MySpec.components.schemas.Bob; // <-- this is the starting point for the query
validate(bob, 'a.b.c'); <-- use bob as the source, and a.b.c as the path to search

function validate(schema: SchemaObject, path: string): boolean {
	return schema.findPath(path) !== undefined;

}

3. Now, obviously, the SchemaObject type doesn't have a prototype, so I can't extend it, but if it were an interface, I'd do something like this:

	declare module 'openapi-typescript' {
	    export interface SchemaObject {
	        findSchema: (path: string) => SchemaObject | undefined;
	    }
	}
	SchemaObject.prototype.findSchema = function (path: string): SchemaObject | undefined {
    // split the path and do a search for the leaf
    // return a value
    }
    }

Can anyone provide input on how I could accomplish this? I'd like to not have to hand code the OpenAPI schema types and interfaces, but would rather use the ones that are already provided here.

[drwpow]

Yeah this is difficult in general to do! While I think this wasn’t originally clear when I started the project, it’s become more apparent with time that openapi-typescript leans heavily into the philosophy of static analysis. In other words, there’s no runtime checking of values. It became clear when building openapi-fetch—I needed a library that didn’t perform runtime validation and instead just relied on static TypeScript inference to infer request & response types in TypeScript, in the IDE. The result is something that’s not only easier to use, but it’s orders of magnitude more performant in the client, and it’s easier to test (in fact, nothing has to be executed—simply run tsc --noEmit and that’s your test suite!).

This is in stark opposition to the runtime analysis approach to Swagger Codegen and other libraries like openapi-typescript-codegen (unrelated to this library). Yes, those do have some element of static analysis, but are by-and-large runtime solutions to this problem—they will throw runtime errors and do runtime transformation of requests and responses.

---

I say that because I see both static analysis and runtime analysis components to your question. This library and its tools can only help out with the former.

For the static analysis part, I’d take a look at the openapi-typescript-helpers package in this repo. Though there’s not documentation, you can see how it’s used in openapi-fetch, such as PathsWithMethod<path, 'get'> returning all paths with a GET response. You could use those helpers instead of findSchema: (path: string).

For the runtime analysis part, there’s no part of this tool that will actually perform the runtime checking. That will either be on your part, or you could look into a generic tool like zod that’s a general-purpose runtime validator. But keep in mind that Zod is probably not the best thing to do either in a browser or a production server, and is probably best suited for local testing or as part of a build step.

[ballcoach12]

Thanks @drwpow. I ended up bringing in a different library that provided more interfaces and classes and fewer type declarations. While I didn't end up modifying the prototype, I did manage to get an implementation up and running.