chore: apiSpec may be const literal

[duncanbeevers]

🐸 Problem to Solve

The middleware may be instantiated with a string (path-on-disk to schema document) or with an object literal of the schema.

In Typescript, it is possible to import .json files as modules; however the types of their fields are "loose" (eg; the file ['foo', bar'] would be typed as string[]
In order to get stronger typing on imported schemas, they can also be re-emitted as Typescript variables with an as const declaration.

const json = ['foo', 'bar'] as const;

In this case, the json const is typed as its literal value readonly ['foo', 'bar'].
This is great, and can be really helpful both when developing, and at run-time.

However, the express-openapi-validator middleware is unhappy with such as const schemas, since the OpenAPIV3.Document type has many mutable fields.

👑 Proposed Solution

Through the type system, promise that the express-openapi-validator won't mangle your as const schema.

The middleware is already gentle with the schema, so this is a type-only change.

The change was motivated by the discovery that passing the schema object to other utilities (eg; openapi-typescript) may cause it to be mutated.

The implementation of DeepImmutable is lifted directly from this comment on the TypeScript repo.

[cdimascio]

I see this json schema is removed... what is the impact of this change on passing a json schema directly in code, similar to what this test previously accepted?

[duncanbeevers]

The as const schema is stricter in every way, so existing inline schemas should continue to type-check in the same way.

If a schema is declared as an untyped variable (and not as const) and passed here it may have looser guarantees than if it were declared inline, due to lack of excess property checks.