Skip to content

0.3.0

Choose a tag to compare

@vxnsin vxnsin released this 07 Oct 07:41
· 122 commits to main since this release

inkan 0.3.0

New

  • 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.