fetchMetadata

Getting Route Metadata

A fetched client gets the server's own compiled functions, so they always match it.

Adding the Middleware

Import mionFetchMetadata from @mionjs/router/middlewares and add it to your routes. Only an API whose clients fetch metadata needs it.

import {createMionRouter, Routes} from '@mionjs/router';
import {mionFetchMetadata} from '@mionjs/router/middlewares';

const mion = createMionRouter();

const routes = {
  // at the root, before any route or group, or the router refuses it
  mionFetchMetadata,
  sayHello: mion.route((ctx, name: string): string => `Hello ${name}`),
} satisfies Routes;

const myApi = mion.initRoutes(routes);

export type MyApi = typeof myApi;

What the Middleware Answers

Given a list of route ids, it returns the metadata of each route and of every middleware that runs with it.

Why Metadata Is Public

Any client can ask for any route's metadata, without logging in. A client with bundled metadata has the same metadata in its JavaScript. Treat it like a public API schema: it shows your types, never your data.

Listing Every Method

A client written without mion can POST this body to any route path to list every public route and middleware, and the ids of your batches, so it can call a batch by id. The route at that path does not run.

{"mionFetchMetadata": [[], "all"]}

Method List Limit

When the API has more routes and middleware than the getAllRemoteMethodsMaxNumber router option, you get no full list: the answer has only the ids you sent, no batch ids, and truncated: true.

import {createMionRouter} from '@mionjs/router';

// list up to 200 methods when a client asks for all of them (100 by default)
export const mion = createMionRouter({getAllRemoteMethodsMaxNumber: 200});

Disabling Routes Metadata Bundling

Set client: {routes: 'fetch'} in your client build, then call useFetchMetadata once, next to initClient, with the client's middlewares.mionFetchMetadata. The server must also add the middleware.

import {defineConfig} from 'vite';
import {mionVitePlugin} from '@mionjs/devtools/vite';

export default defineConfig({
  plugins: [
    mionVitePlugin({
      // fetch each route's metadata from the server on first use
      client: {routes: 'fetch'},
    }),
  ],
});

import {initClient} from '@mionjs/client';
import {useFetchMetadata} from '@mionjs/client/middlewares';
import type {MyApi} from './metadata-fetch.routes.ts';

const {routes, middlewares} = initClient<MyApi>({
  baseURL: 'http://localhost:3000',
});
useFetchMetadata(middlewares.mionFetchMetadata);

// the first call also fetches the metadata of sayHello
const [greeting] = await routes.sayHello('Ana').call();
console.log(greeting);

Fetching Only What the Build Misses

If you keep bundling on and also call useFetchMetadata, the client fetches metadata only for calls the build could not bundle: calls whose route a generic helper hides. Fetched metadata never replaces a bundled route. To keep every call bundled, see Generic Call Helpers.

The First Call

A route's first call goes out right away and asks for the metadata in the same request. The server validates the params and answers with the result and the metadata. The client saves the metadata, so later calls also validate in the browser before sending.

Saving Fetched Metadata

The client saves what it fetched, per server, so a later visit does not ask again. Pick where with the storageEngine client option. Where the store cannot open, like on the server or in a browser that blocks IndexedDB, the client keeps it in memory.

import {initClient, requestPersistentStorage} from '@mionjs/client';
import {useFetchMetadata} from '@mionjs/client/middlewares';
import type {MyApi} from './metadata-fetch.routes.ts';

const {middlewares} = initClient<MyApi>({
  baseURL: 'http://localhost:3000',
  storageEngine: 'indexeddb',
});
useFetchMetadata(middlewares.mionFetchMetadata);

// ask the browser to keep the cache when it clears storage, best after a user action
document
  .querySelector('#settings')
  ?.addEventListener('click', () => requestPersistentStorage());

Using Your Own Store

Set storageEngine to a function that opens your own store. The client calls it once. Your store implements MetadataStore from @mionjs/client: readAll, write, remove and clear, each for one server's baseURL.

import {initClient, type MetadataStore} from '@mionjs/client';
import type {MyApi} from './metadata-fetch.routes.ts';

// your app's own storage, like a native app's database
declare function openAppStore(): Promise<MetadataStore | undefined>;

export const {routes, middlewares} = initClient<MyApi>({
  baseURL: 'http://localhost:3000',
  // returning undefined keeps the cache in memory
  storageEngine: openAppStore,
});

API Version Check

mionFetchMetadata sends the server's API version in the x-build-version header of every response, and the client compares it with the version it was built with. A mismatch does not stop the call: reload the app or rebuild the client to fix it. Use mionSyncRoutes to stop such calls, or run mion api-check to catch a mismatch before you deploy.

Build Checks

The build fails on a setup that would fail at runtime. Look up any name in All Diagnostics.