@mapled/next 0.5.0 → 0.7.0

package/README.md

@@ -47,6 +47,32 @@ posts[0].expanded?.author; // { id, data: { name: "Ada" } } or null
 
 Every call reads the latest **published release** — drafts never leak. Fetches are tagged `mapled` and `mapled:<collection>` and default to `revalidate: 3600`; the webhook below refreshes them the moment someone publishes.
 
+### Typed by your schema
+
+`npx @mapled/cli types generate` writes `mapled-types.ts`: one interface per collection and single, and a `MapledSchema` that ties them together. Hand it to the client once and every read is typed by its key:
+
+```ts
+import type { MapledSchema } from "./mapled-types";
+
+const mapled = createClient<MapledSchema>({ key: process.env.MAPLED_KEY! });
+
+const { records } = await mapled.getRecords("articles"); // records[0].data is an Article
+const home = await mapled.getSingle("homepage");          // Homepage | null
+await mapled.getRecords("artcles");                       // type error — no such collection
+```
+
+Without a schema the client behaves as before: any key, `Record<string, unknown>` data, or the type you name per call (`getRecords<Article>("articles")`). `createAppClient<MapledSchema>` types live data the same way — `db.create("orders", data)` wants an `Order`. `mapled doctor` tells you when the generated file is behind the schema.
+
+### Renamed fields
+
+When a field's key is renamed in Mapled, nothing breaks: the old key stays as an alias — delivered next to the new one, accepted in `filter`, `sort`, `fields`, `expand` and in live-data writes — until someone removes it in Field settings. Answers that still serve a previous key name it (`aliases: { products: { price: "amount" } }` on a list result), and outside production the client says so once per key:
+
+```
+[mapled] “price” in “products” was renamed to “amount”. The old key keeps working until its alias is removed in Mapled — use “amount” instead.
+```
+
+Move the code to the new key, run `mapled types generate` (the old key is typed `@deprecated` until then), and remove the alias. In production the client stays silent.
+
 ### Pin a release
 
 A page that makes several reads can pin them all to one release, so a publish landing mid-render can't mix two versions:
@@ -131,7 +157,7 @@ The server key reaches only operational collections with access class `public`/`
 
 ## API
 
-- `createClient({ key, apiUrl?, release? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`, `getRelease()`
+- `createClient({ key, apiUrl?, release? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`, `getRelease()`; `createClient<MapledSchema>(…)` with the generated `MapledSchema` types every read by its key (`MapledClient<S>`, `MapledAppClient<S>` name the typed clients)
 - list `opts`: `filter` (a value for equality, or `{ eq, ne, lt, lte, gt, gte, in, contains }` — text takes eq/ne/in/contains, numbers and dates comparisons, booleans eq/ne, image and relation ids eq/ne/in; a one-to-many relation matches when it includes the id), `sort` (`"field"` / `"-field"`, not on relations or images), `limit` (≤100), `offset`
 - every read: `expand` (relation keys, dotted for a second level), `fields` (data keys to keep), `release` (pin to a published release), `revalidate`, `tags`; a query the schema can't answer fails with a 400 `INVALID_QUERY` message, and errors carry the API's `code` on `MapledError`
 - `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler

package/dist/index.d.ts

@@ -51,6 +51,10 @@ export type ListResult<T = Record<string, unknown>> = {
     records: MapledRecord<T>[];
     total: number;
     release: number;
+    /** Renamed fields whose previous keys this answer still serves, by
+        collection: `{ products: { price: "amount" } }`. Absent when nothing
+        was renamed. Outside production the SDK warns about each once. */
+    aliases?: Record<string, Record<string, string>>;
 };
 export type ImageOptions = {
     /** Snapped up to the nearest preset (64 … 2560); never upscaled past the source. */
@@ -73,8 +77,63 @@ export declare class MapledError extends Error {
     code: string | undefined;
     constructor(status: number, message: string, code?: string);
 }
-export type MapledClient = ReturnType<typeof createClient>;
-export type MapledAppClient = ReturnType<typeof createAppClient>;
+/** The shape of the `MapledSchema` that `mapled types generate` writes:
+    collections and singles by key, each the type of a record's data.
+    Pass it as `createClient<MapledSchema>(…)` and every read is typed by
+    its key; without it the client accepts any key and answers
+    `Record<string, unknown>` (or the type you name per call). */
+export type ContentSchema = {
+    collections?: object;
+    singles?: object;
+};
+type Data = Record<string, unknown>;
+type AnyMap = Record<string, Data>;
+type CollectionsOf<S extends ContentSchema> = S["collections"] extends object ? S["collections"] : AnyMap;
+type SinglesOf<S extends ContentSchema> = S["singles"] extends object ? S["singles"] : AnyMap;
+/** Any key on an untyped client; on a typed one, a key it knows — so an
+    explicit `getRecords<Article>("articles")` keeps working either way. */
+type LooseKey<S extends ContentSchema, M> = ContentSchema extends S ? string : keyof M & string;
+/** Writes on a typed client take the collection's own type, never a guess. */
+type LooseData<S extends ContentSchema, T> = ContentSchema extends S ? T : never;
+export interface MapledClient<S extends ContentSchema = ContentSchema> {
+    /** Published records of a collection, with filters/sort/pagination. */
+    getRecords<K extends keyof CollectionsOf<S> & string>(collection: K, opts?: ListOptions): Promise<ListResult<CollectionsOf<S>[K]>>;
+    getRecords<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, opts?: ListOptions): Promise<ListResult<T>>;
+    /** One published record by id, or null when it isn't in the release. */
+    getRecord<K extends keyof CollectionsOf<S> & string>(collection: K, id: string, opts?: ReadOptions): Promise<MapledRecord<CollectionsOf<S>[K]> | null>;
+    getRecord<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, id: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
+    /** One published record by the collection's slug field, or null. */
+    getRecordBySlug<K extends keyof CollectionsOf<S> & string>(collection: K, slug: string, opts?: ReadOptions): Promise<MapledRecord<CollectionsOf<S>[K]> | null>;
+    getRecordBySlug<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, slug: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
+    /** The record of a single (e.g. "homepage"), or null before publish. */
+    getSingle<K extends keyof SinglesOf<S> & string>(key: K, opts?: ReadOptions): Promise<MapledRecord<SinglesOf<S>[K]> | null>;
+    getSingle<T = Data>(key: LooseKey<S, SinglesOf<S>>, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
+    /** The release the site is reading right now — the latest published
+        one, with the moment it went live — or null before the first
+        publish. Never cached: it's the one short-lived pointer of the
+        delivery API; pass its number as `release` to pin a render. */
+    getRelease(): Promise<{
+        release: number;
+        publishedAt: string;
+    } | null>;
+}
+export interface MapledAppClient<S extends ContentSchema = ContentSchema> {
+    list<K extends keyof CollectionsOf<S> & string>(collection: K, opts?: AppListOptions): Promise<{
+        records: AppRecord<CollectionsOf<S>[K]>[];
+        total: number;
+    }>;
+    list<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, opts?: AppListOptions): Promise<{
+        records: AppRecord<T>[];
+        total: number;
+    }>;
+    get<K extends keyof CollectionsOf<S> & string>(collection: K, id: string): Promise<AppRecord<CollectionsOf<S>[K]> | null>;
+    get<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, id: string): Promise<AppRecord<T> | null>;
+    create<K extends keyof CollectionsOf<S> & string>(collection: K, data: CollectionsOf<S>[K]): Promise<AppRecord<CollectionsOf<S>[K]>>;
+    create<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, data: LooseData<S, T>): Promise<AppRecord<T>>;
+    update<K extends keyof CollectionsOf<S> & string>(collection: K, id: string, data: CollectionsOf<S>[K]): Promise<AppRecord<CollectionsOf<S>[K]>>;
+    update<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, id: string, data: LooseData<S, T>): Promise<AppRecord<T>>;
+    remove(collection: LooseKey<S, CollectionsOf<S>>, id: string): Promise<void>;
+}
 export type AppRecord<T = Record<string, unknown>> = {
     id: string;
     data: T;
@@ -87,41 +146,16 @@ export type AppListOptions = {
     limit?: number;
     offset?: number;
 };
-export declare function createClient(config: {
+export declare function createClient<S extends ContentSchema = ContentSchema>(config: {
     key: string;
     apiUrl?: string;
     release?: number;
-}): {
-    /** Published records of a collection, with filters/sort/pagination. */
-    getRecords<T = Record<string, unknown>>(collection: string, opts?: ListOptions): Promise<ListResult<T>>;
-    /** One published record by id, or null when it isn't in the release. */
-    getRecord<T = Record<string, unknown>>(collection: string, id: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
-    /** One published record by the collection's slug field, or null. */
-    getRecordBySlug<T = Record<string, unknown>>(collection: string, slug: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
-    /** The record of a single (e.g. "homepage"), or null before publish. */
-    getSingle<T = Record<string, unknown>>(key: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
-    /** The release the site is reading right now — the latest published
-        one, with the moment it went live — or null before the first
-        publish. Never cached: it's the one short-lived pointer of the
-        delivery API; pass its number as `release` to pin a render. */
-    getRelease(): Promise<{
-        release: number;
-        publishedAt: string;
-    } | null>;
-};
+}): MapledClient<S>;
 /** Live data (operational collections): the site's backend reads and
     writes records that take effect immediately — no publish involved.
     Server-side only: the server key must never reach the browser. */
-export declare function createAppClient(config: {
+export declare function createAppClient<S extends ContentSchema = ContentSchema>(config: {
     serverKey: string;
     apiUrl?: string;
-}): {
-    list<T = Record<string, unknown>>(collection: string, opts?: AppListOptions): Promise<{
-        records: AppRecord<T>[];
-        total: number;
-    }>;
-    get<T = Record<string, unknown>>(collection: string, id: string): Promise<AppRecord<T> | null>;
-    create<T = Record<string, unknown>>(collection: string, data: T): Promise<AppRecord<T>>;
-    update<T = Record<string, unknown>>(collection: string, id: string, data: T): Promise<AppRecord<T>>;
-    remove(collection: string, id: string): Promise<void>;
-};
+}): MapledAppClient<S>;
+export {};

package/dist/index.js

@@ -1,6 +1,34 @@
 /** Mapled delivery client for Next.js sites.
     Reads published content only — pair it with the revalidation webhook
     handler from "@mapled/next/server" for instant updates on publish. */
+/** Renamed fields (previous keys): Mapled keeps serving a renamed field
+    under its old key — and accepting it in filters, sorts and writes —
+    until the alias is removed in Field settings, and names such keys in
+    its answers. Outside production each is reported once per process, so
+    the site moves to the new key before the alias goes. */
+const KEY_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const reported = new Set();
+function reportAliases(body) {
+    if (typeof process !== "undefined" && process.env?.NODE_ENV === "production")
+        return;
+    const aliases = body?.aliases;
+    if (!aliases || typeof aliases !== "object")
+        return;
+    for (const [collection, keys] of Object.entries(aliases)) {
+        if (!keys || typeof keys !== "object" || !KEY_RE.test(collection))
+            continue;
+        for (const [previous, current] of Object.entries(keys)) {
+            // keys are the project's content: only what looks like a key is printed
+            if (typeof current !== "string" || !KEY_RE.test(previous) || !KEY_RE.test(current))
+                continue;
+            const id = `${collection}.${previous}`;
+            if (reported.has(id))
+                continue;
+            reported.add(id);
+            console.warn(`[mapled] “${previous}” in “${collection}” was renamed to “${current}”. The old key keeps working until its alias is removed in Mapled — use “${current}” instead.`);
+        }
+    }
+}
 /** URL of an image or file value (an asset id) — the original, or a
     resized variant made on first request and cached from then on. */
 export function assetUrl(id, opts = {}) {
@@ -95,7 +123,9 @@ export function createClient(config) {
         const res = await fetch(`${base}${path}${qs ? `?${qs}` : ""}`, init);
         if (!res.ok)
             throw await failure(res);
-        return { status: res.status, body: (await res.json()) };
+        const body = (await res.json());
+        reportAliases(body);
+        return { status: res.status, body };
     }
     /** expand / fields on every read. */
     const readParams = (search, opts) => {
@@ -118,8 +148,7 @@ export function createClient(config) {
             throw err;
         }
     };
-    return {
-        /** Published records of a collection, with filters/sort/pagination. */
+    const client = {
         async getRecords(collection, opts = {}) {
             const search = new URLSearchParams();
             for (const [k, v] of Object.entries(opts.filter ?? {})) {
@@ -144,22 +173,15 @@ export function createClient(config) {
             const { body } = await call(`/v1/delivery/collections/${encodeURIComponent(collection)}/records`, search, opts, [`mapled:${collection}`]);
             return body;
         },
-        /** One published record by id, or null when it isn't in the release. */
         getRecord(collection, id, opts = {}) {
             return one(`/v1/delivery/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`, opts, `mapled:${collection}`);
         },
-        /** One published record by the collection's slug field, or null. */
         getRecordBySlug(collection, slug, opts = {}) {
             return one(`/v1/delivery/collections/${encodeURIComponent(collection)}/records/by-slug/${encodeURIComponent(slug)}`, opts, `mapled:${collection}`);
         },
-        /** The record of a single (e.g. "homepage"), or null before publish. */
         getSingle(key, opts = {}) {
             return one(`/v1/delivery/singles/${encodeURIComponent(key)}`, opts, `mapled:${key}`);
         },
-        /** The release the site is reading right now — the latest published
-            one, with the moment it went live — or null before the first
-            publish. Never cached: it's the one short-lived pointer of the
-            delivery API; pass its number as `release` to pin a render. */
         async getRelease() {
             const res = await fetch(`${base}/v1/delivery/release`, {
                 headers: { "x-mapled-key": config.key },
@@ -173,6 +195,8 @@ export function createClient(config) {
             return { release: body.release, publishedAt: body.publishedAt };
         },
     };
+    // the same functions behind both overloads: the typed one only narrows
+    return client;
 }
 /** Live data (operational collections): the site's backend reads and
     writes records that take effect immediately — no publish involved.
@@ -204,10 +228,12 @@ export function createAppClient(config) {
             }
             throw new MapledError(res.status, message);
         }
-        return (await res.json());
+        const body = (await res.json());
+        reportAliases(body);
+        return body;
     }
     const collectionPath = (c) => `/v1/app/collections/${encodeURIComponent(c)}/records`;
-    return {
+    const client = {
         async list(collection, opts = {}) {
             const search = new URLSearchParams();
             for (const [k, v] of Object.entries(opts.filter ?? {})) {
@@ -244,4 +270,5 @@ export function createAppClient(config) {
             await call("DELETE", `${collectionPath(collection)}/${encodeURIComponent(id)}`);
         },
     };
+    return client;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Read published Mapled content in a Next.js site \u2014 delivery client, ISR tags, and a revalidation webhook handler.",
   "license": "MIT",
   "homepage": "https://mapled.io",