You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
More schema power.t.date() takes ISO date-time strings (or Dates) and hands the
handler a Date; answers send it back as an ISO string. .refine(fn, message) adds your
own rules, .transform(fn) changes the parsed value, t.discriminated(key, options) picks
one branch by its tag (OpenAPI oneOf with a discriminator), and t.lazy(() => schema)
makes recursive shapes possible. Thanks @AndrewCMD!
(#13, #22)
The help text is coloured, and so are logs in GitHub Actions (NO_COLOR still turns it off).
Request ids. Every request gets one: the x-request-id it came with when that looks safe,
a fresh UUID otherwise. It is ctx.id in the handler, goes back out as a header, and lands in
the log line, the inspector and every problem document as requestId. requestId: "x-correlation-id"
picks another header, requestId: false turns it off. (#15)
Structured logs.log: "json" writes one JSON line per request (time, id, method, path,
route, status, ms, notes), and logger: (entry) => … hands every entry to your own logger
instead of the console. (#15)
Edit a request on the docs page. Every example has an edit button: params, query,
headers and body, filled in from the example, sent as you changed them. An edited request
says so and never counts towards a route's seal. reset brings the example back, and curl copies the request as a curl command. (#8)
A token for the docs page. A field at the top puts an authorization or x-api-key
header on every request from the page. It lives in sessionStorage, so it is gone with
the tab, never lands in a URL, and shows as ••• in a copied curl command.
(#8)
Inspector: replay. Sends a request again and shows the old and the new answer side by
side, with whether they match (a requestId alone does not count as a change). Secret
headers are not sent again, and the page says so. The replay shows up in the log as replay of #n. (#7)
Inspector: copy as example. Turns a request into a ready examples: [...] entry with
its params, query, body and status, plus any custom headers, but never secret headers or
the ones every client sends. Paste it into the route and inkan check holds it from then on.
(#7)
inkan examples. Pulls a complete example project into a folder, explained file by file:
a README per example that says what to read in which order, numbered comments in the code,
something to change first, and a "try this: break it on purpose" list that shows what inkan
catches. Six of them, in reading order: hello, tea-shop, auth, testing, openapi, deploy. npx @vxnsin/inkan examples asks which one, --list lists them, inkan examples tea-shop my-shop goes straight there. A folder that is not empty needs --force. The templates ship inside the package, so it works offline and fits the installed
version, and every one of them passes inkan check --strict in CI.
(#1)
inkan diff. Compares a saved OpenAPI document with the app, or two documents, and says
what would break a client written against the old one: a route or a status that is gone, a
field or parameter that is required now, a value a request may no longer send, a tighter
limit or pattern, a field an answer may leave out or set to null now. Requests may only get
looser and answers only stricter. Everything else is listed as safe. It exits with 1 when
something breaks, so CI can ask for a major version; --json for tools. Also as diffOpenAPI(before, after). (#11)
Examples that build on each other. An example can keep values from its answer
(keep: { id: "body.id" }, also headers.… and status), and another one can run after it (after: "POST /teas > a new oolong") and use them as {id} in its params,
query, headers and body. beforeEach runs once before the whole chain, the order comes from after rather than from the files, and a broken step, an after that points nowhere or a
circle each fail with a sentence that says which. The docs page runs the chain when you
press send, and the tea-shop example shows it. (#10)
Streams. A handler may return a Node Readable, a web ReadableStream or any async
iterable; it goes out piece by piece, with backpressure, and stops when the client leaves.
(#5)
Server-sent events.sse(async function* (signal) { … }) answers with an event stream,
and t.events({ tick: … }) puts one schema per event into the contract and into OpenAPI as text/event-stream. The signal fires when the client goes away, quiet streams get a
keep-alive comment, and in development an event that breaks its schema ends the stream with
an error event. inkan check, app.inject({ events: n }) and the docs page read as many
events as an example expects, so endless streams can be examples too.
(#5)
Uploads.t.file().max(bytes).accept("image/*") in a body makes it multipart/form-data, parsed by the platform itself, with no dependency. Files arrive as { name, type, size, data }, the fields next to them are coerced like a query, and a file
that is too big or of the wrong type is a 400 that says which. fileExample(name, content, type) puts a file into an example; inject takes a FormData too.
(#5)
A typed client, with no codegen.client<typeof api>(baseUrl) from @vxnsin/inkan/client takes its types from the app: paths, params, query, body and every
answer per status, with Dates as the strings they arrive as. A wrong path, a missing param
or a body of the wrong shape does not compile. Failures come back as problem documents,
never as thrown errors. It is a few lines around fetch with no server code in it, so it
runs in a browser too; { fetch } and { headers } (also as a function, for fresh tokens)
are optional. The routes have to be defined in a chain (inkan().get(…).post(…), also mount) for the type to see them. (#2)
Changed
toJSONSchema() keeps named schemas in $defs and refers to them, instead of writing them
out inline, so recursive schemas work there too.
In production, requests are now logged as JSON lines by default (before: not at all). log: false keeps it quiet. Development keeps the short coloured line.
Inspector log entries carry example and request.clipped. A request whose body was too
long to keep whole is not offered for replay, and its example leaves the body out instead
of guessing.