@croutonian/with-openapi 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -660,15 +660,47 @@ type MatchedOperation<Document, Route extends string, Method extends string> = {
  */
 type MatchedFor<Document> = { [Route in RoutesOf<Document>]: { [Method in MethodsOf<Document, Route>]: MatchedOperation<Document, Route, Method> }[MethodsOf<Document, Route>] }[RoutesOf<Document>];
 /**
- * What lands at `ctx.openapi` for a given document.
+ * Whether `Key` is set to `'pass'` — or might be.
  *
- * Falls back to the unspecialized {@link OpenApiContribution} when the
- * document arrived without its literal type — annotated `: OpenAPIObject`,
- * say. `RoutesOf` is `never` there, which would otherwise leave a union with
- * no `matched: true` branch at all and break every existing consumer.
- * Degrading to today's shape is what keeps this change additive.
+ * Everything here fails *safe*: the unmatched branch is only dropped when the
+ * config provably cannot produce one. A widened config satisfies
+ * `'pass' extends string`, so it keeps the branch rather than promising a
+ * `matched: true` the runtime may not deliver.
  */
-type ContributionFor<Document> = [RoutesOf<Document>] extends [never] ? OpenApiContribution : MatchedFor<Document> | OpenApiUnmatched;
+type MayPass<Config, Key extends string> = Key extends keyof Config ? 'pass' extends Config[Key] ? true : false : false;
+/**
+ * Whether a `skip` predicate might fire.
+ *
+ * Asks whether `skip` could *possibly* be a function, not whether it
+ * definitely is. `skip: condition ? fn : undefined` has type
+ * `Fn | undefined`, and a check of the second kind reads that as "no skip"
+ * and drops the branch — while at runtime the predicate fires whenever the
+ * condition holds, handing a handler an unmatched contribution the compiler
+ * said could not exist.
+ */
+type HasSkip<Config> = 'skip' extends keyof Config ? [Config['skip']] extends [undefined] ? false : true : false;
+/**
+ * Whether this config can produce an unmatched contribution at all.
+ *
+ * Mirrors the three runtime branches that call `unmatched()`: a `skip` that
+ * fired, `onUnknownRoute: 'pass'` with no route match, `onUnknownMethod:
+ * 'pass'` with no operation. On the defaults none of them can, because both
+ * options default to `'reject'` and answer the request themselves.
+ */
+type CanBeUnmatched<Config> = MayPass<Config, 'onUnknownRoute'> extends true ? true : MayPass<Config, 'onUnknownMethod'> extends true ? true : HasSkip<Config> extends true ? true : false;
+/**
+ * What lands at `ctx.openapi` for a given document and config.
+ *
+ * Two reductions, in order. Handed a document that arrived without its
+ * literal type — annotated `: OpenAPIObject`, say — `RoutesOf` is `never`,
+ * and this degrades to the unspecialized {@link OpenApiContribution}; without
+ * that, the union would have no `matched: true` branch at all and every
+ * existing consumer would break. Otherwise the unmatched branch is dropped
+ * unless the config can actually produce one, so a downstream middleware or
+ * handler can read `route`, `operationId` and `params` without a guard for a
+ * case that cannot happen.
+ */
+type ContributionFor<Document, Config = WithOpenApiConfig> = [RoutesOf<Document>] extends [never] ? OpenApiContribution : CanBeUnmatched<Config> extends true ? MatchedFor<Document> | OpenApiUnmatched : MatchedFor<Document>;
 //#endregion
 //#region src/with-openapi.d.ts
 /**
@@ -681,15 +713,19 @@ type ContributionFor<Document> = [RoutesOf<Document>] extends [never] ? OpenApiC
  * handler-taking forms fall through to the general signatures below it, where
  * `ctx.openapi` keeps its unspecialized shape.
  *
+ * The whole config is captured, not just the document: `onUnknownRoute`,
+ * `onUnknownMethod` and `skip` are what decide whether an unmatched
+ * contribution is reachable, and on the defaults it is not — so a downstream
+ * middleware or handler gets `matched: true` already narrowed, with no guard
+ * for a case the config rules out.
+ *
  * The runtime is untouched: this re-describes what `defineMiddleware` already
  * returns. That makes the description an assertion we own — if `ParamsFor`
  * ever disagrees with what the middleware actually deserializes, the types
  * are what lie, and nothing here would catch it.
  */
 interface TypedByDocument {
-  <const Document extends OpenAPIObject>(config: Omit<WithOpenApiConfig, 'document'> & {
-    document: Document;
-  }): SingleKeyEntry<'openapi', Record<never, never>, ContributionFor<Document>>;
+  <const Config extends WithOpenApiConfig>(config: Config): SingleKeyEntry<'openapi', Record<never, never>, ContributionFor<Config['document'], Config>>;
 }
 /**
  * Middleware that holds an API to its own description.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@croutonian/with-openapi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "OpenAPI middleware for @supabase/middleware. Matches each request against an OpenAPI 3.1 document, optionally rejects the ones it does not describe, contributes the matched operation and validated params to ctx, and optionally serves a Scalar API reference.",
   "keywords": [
     "openapi",