@nohead/sdk 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ Changes to `@nohead/sdk` that you can notice. Versions follow
 releases; a change that could break your code is a major one. Each release's
 section is its GitHub release's notes.
 
+## 0.14.0
+
+- `noheadLoader` gives each collection its schema and TypeScript type, from
+  the collection's fields in Nohead (Astro 6 or later, through its
+  `createSchema`), so `defineCollection({ loader: noheadLoader(…) })` is
+  typed without a hand-written Zod schema. Relations are `reference()`s to
+  the collection named like their target's slug, dates are `Date`s, and
+  expanded assets and relations are `EmbeddedAsset`s and `EmbeddedRecord`s.
+  It takes the key's `schema:read` scope. A `schema` given to
+  `defineCollection` still takes its place.
+- The Astro image service takes defaults for every image from its `config`
+  in astro.config: `quality` and `format`. An image's own options win.
+
 ## 0.13.0
 
 - `@nohead/sdk/astro`: `noheadLoader`, a loader for Astro's content

package/README.md

@@ -328,7 +328,7 @@ imageUrl(asset.image_url!, { width: 400, dpr: 2, options: ["bl:2"] })
 Frameworks' image components, with `srcset` and all, take a loader from it:
 
 - **Next.js:** a file named by `images.loaderFile` in next.config: `export { nextImageLoader as default } from "@nohead/sdk/images"`, then `<Image src={asset.image_url} … />`. It serves WebP, as Next.js's own optimizer does by default, unless the URL names a format (`@avif` for AVIF, which `images.formats` can't ask a loader for): ``src={`${asset.image_url}@svg`}`` keeps an SVG a vector.
-- **Astro:** `image: { service: { entrypoint: "@nohead/sdk/astro/image-service" } }` in astro.config, then `<Image src={asset.image_url} width={…} height={…} alt={…} />`. It serves WebP unless a `format` says otherwise: give an SVG `format="svg"` to keep it a vector (an asset's `content_type` tells). Pass `width` and `height`, which expanded assets carry; `inferSize` would need the image host in Astro's `image.domains`. Needs Astro 5.9 or later.
+- **Astro:** `image: { service: { entrypoint: "@nohead/sdk/astro/image-service" } }` in astro.config, then `<Image src={asset.image_url} width={…} height={…} alt={…} />`. It serves WebP unless a `format` says otherwise: give an SVG `format="svg"` to keep it a vector (an asset's `content_type` tells). Pass `width` and `height`, which expanded assets carry; `inferSize` would need the image host in Astro's `image.domains`. Defaults for every image go in the service's `config`, and an image's own options win: `service: { entrypoint: "@nohead/sdk/astro/image-service", config: { quality: 70 } }` (`format` too). Needs Astro 5.9 or later.
 - **Nuxt Image:** a custom provider file in nuxt.config's `image.providers`: `export { nuxtImageProvider as default } from "@nohead/sdk/images"` (Nuxt Image 1: `export { getImage } from "@nohead/sdk/images"`).
 
 The loaders leave other images, the site's own, as they are.
@@ -380,27 +380,19 @@ Search needs the `search:read` scope and covers every collection the key can rea
 
 ## Astro
 
-`@nohead/sdk/astro` loads collections into Astro's content collections (Astro 5.9 or later), so pages read them with `getCollection`, `getEntry`, `reference()` and `render()`:
+`@nohead/sdk/astro` loads collections into Astro's content collections (Astro 5.9 or later), so pages read them with `getCollection`, `getEntry`, `reference()` and `render()`. On Astro 6 or later, the loader also gives each collection its schema and TypeScript type, from the collection's fields in Nohead (on Astro 5, give each collection a `schema`, under [Schema and types](#schema-and-types)):
 
 ```ts
 // src/content.config.ts
-import { defineCollection, reference } from "astro:content"
-import { z } from "astro/zod"
+import { defineCollection } from "astro:content"
 import { noheadLoader } from "@nohead/sdk/astro"
 
 // Astro reads .env into import.meta.env, not process.env.
 const apiKey = import.meta.env.NOHEAD_API_KEY
-const image = z.object({
-  image_url: z.string(),
-  width: z.number(),
-  height: z.number(),
-  alt: z.string().optional(),
-})
 
 export const collections = {
   people: defineCollection({
     loader: noheadLoader({ collection: "people", apiKey }),
-    schema: z.object({ name: z.string(), slug: z.string() }),
   }),
   posts: defineCollection({
     loader: noheadLoader({
@@ -409,13 +401,6 @@ export const collections = {
       body: "body",
       apiKey,
     }),
-    schema: z.object({
-      title: z.string(),
-      slug: z.string(),
-      date: z.coerce.date(),
-      authors: z.array(reference("people")),
-      cover: image.optional(),
-    }),
   }),
 }
 ```
@@ -423,28 +408,57 @@ export const collections = {
 ```astro
 ---
 // src/pages/posts/[slug].astro
-import { getCollection, render } from "astro:content"
+import { getCollection, getEntry, render } from "astro:content"
 import { Image } from "astro:assets"
 
 export async function getStaticPaths() {
   const posts = await getCollection("posts")
   return posts.map((post) => ({ params: { slug: post.data.slug }, props: { post } }))
 }
-const { post } = Astro.props
+const { post } = Astro.props // post.data.title: string, post.data.date: Date
 const { Content } = await render(post)
-const { cover } = post.data
+const authors = await Promise.all(post.data.authors.map((author) => getEntry(author)))
+const { cover } = post.data // an image field's assets have their URL and size
 ---
-{cover && <Image src={cover.image_url} width={cover.width} height={cover.height} alt={cover.alt ?? ""} />}
+<h1>{post.data.title}</h1>
+<p>By {authors.map((author) => author?.data.name).join(" and ")}</p>
+{cover && <Image src={cover.image_url!} width={cover.width!} height={cover.height!} alt={cover.alt ?? ""} />}
 <Content />
 ```
 
-- **Entries.** Each record becomes an entry whose `id` is the record ID and whose `data` is its fields, checked by the collection's `schema`. Collections load when the site builds and when `astro dev` starts. Each load lists the whole collection, removes the entries of records that are gone, and skips records that haven't changed.
+### Schema and types
+
+Before, each collection repeated its fields as a Zod schema:
+
+```ts
+posts: defineCollection({
+  loader: noheadLoader({ collection: "posts", expand: ["cover"], body: "body", apiKey }),
+  schema: z.object({
+    title: z.string(),
+    date: z.coerce.date(),
+    authors: z.array(reference("people")),
+    cover: z.object({ image_url: z.string(), width: z.number(), height: z.number() }).optional(),
+    // …and every other field
+  }),
+}),
+```
+
+Now the loader reads the collection's fields when Astro syncs (`astro dev`, `astro build`, `astro sync`) and writes both the schema and the type, so `getCollection("posts")` is typed with none of that:
+
+- Text fields are strings; integers and decimals, numbers; dates, `Date`s; enums, their options; booleans, `boolean` (`false` when unset); JSON, `unknown`. A multiple field is an array.
+- A required field is required, others optional. An expanded asset or relation is always optional, since one deleted or unpublished since is left out.
+- A relation is a `reference()` to the Astro collection named like its target's slug, so name your collections after their slugs, and define one for every target that relations point to (`categories` for a post's `category`), or `getEntry` has nothing to find. Expanded, it is an `EmbeddedRecord`, and an expanded asset an `EmbeddedAsset`. An asset that isn't expanded stays its ID.
+- The `body` field isn't in the data: `render(entry)` has it.
+- The schema takes the key's `schema:read` scope, which published-only keys can have; without it the sync fails and says so.
+- A `schema` given to `defineCollection` takes its place, as in any Astro loader. Use one to transform values, or on Astro 5, which doesn't ask loaders for a schema.
+
+- **Entries.** Each record becomes an entry whose `id` is the record ID and whose `data` is its fields, checked by the collection's schema. Collections load when the site builds and when `astro dev` starts. Each load lists the whole collection, removes the entries of records that are gone, and skips records that haven't changed.
 - **Published only.** Only published records load, whatever the key may read, so a published-only key (`nohead_pk_…`) is enough. `filter` adds conditions (`{ featured: true }`); `filter: { published_at: undefined }` loads every record.
 - **Rich text** reads as HTML (or Markdown with `richText: "markdown"`). `body` names the field that `render(entry)` renders: it moves out of `data` into the entry's rendered content. As Markdown, it goes through Astro's own Markdown pipeline (your plugins, syntax highlighting, `headings`). A record can have several rich text fields and an entry renders one; the others stay in `data` as HTML, for `<Fragment set:html={post.data.summary} />`.
 - **Order.** Astro doesn't keep an order for a collection (from Astro 6, `getCollection` returns entries by ID), so sort what it returns: `posts.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf())`.
 - **Relations** stay record IDs, for `reference("people")` and `getEntry`.
 - **Assets** named in `expand` replace their ID with the asset: `id`, `filename`, `content_type`, and when they have them `alt`, `width`, `height`, `image_url`, `file_url` and `media_url` (`EmbeddedAsset`). With the image service, `@nohead/sdk/astro/image-service` (under [Assets](#assets)), `<Image>` writes sizes and formats into the image's URL. An expanded relation becomes `{ id, data }`. An asset or record deleted since is left out, and so is an unpublished record, unless `filter` loads unpublished entries too.
-- **Empty fields** are left out of `data` rather than `null`, so `.optional()` fits them. Dates and times are strings: `z.coerce.date()` makes them `Date`s.
+- **Empty fields** are left out of `data` rather than `null`, so `.optional()` fits them. Without the loader's schema, dates and times are strings: `z.coerce.date()` makes them `Date`s.
 - **The key** is `apiKey`, or `NOHEAD_API_KEY` from the environment; the other client options (`timeout`, `maxRetries`, `headers`) apply too. Astro keeps `.env` in `import.meta.env`, so pass the key from there as above.
 
 ## Schema

package/dist/astro-image-service.d.ts

@@ -11,7 +11,19 @@
  * attributes, `srcset` for `widths` and `densities`). WebP unless a
  * `format` says otherwise. Other images (the site's own, imported or
  * remote) are served as they are.
+ *
+ * Defaults for every image go in the service's `config`, and an image's own
+ * `quality` or `format` wins:
+ *
+ *   service: { entrypoint: "@nohead/sdk/astro/image-service", config: { quality: 70 } }
  */
 import type { ExternalImageService } from "astro";
-declare const imageService: ExternalImageService;
+/** The service's `config` in astro.config: defaults for every image. */
+export interface ImageServiceConfig {
+    /** 1 to 100, or one of Astro's presets (`"high"` is 80). */
+    quality?: number | "low" | "mid" | "high" | "max";
+    /** `"webp"` unless set. */
+    format?: "webp" | "avif" | "jpeg" | "jpg" | "png";
+}
+declare const imageService: ExternalImageService<ImageServiceConfig>;
 export default imageService;

package/dist/astro-image-service.js

@@ -7,11 +7,15 @@ const imageService = {
     async validateOptions(options, imageConfig, logger) {
         const validated = await baseService.validateOptions(options, imageConfig, logger);
         // So the srcset's <source type> says what the URLs serve.
-        if (isImageUrl(validated.src))
-            validated.format ??= "webp";
+        if (isImageUrl(validated.src)) {
+            // A Picture's <source type> needs `jpeg`, not `jpg`.
+            validated.format ??=
+                formatOf(imageConfig?.service?.config?.format) ?? "webp";
+        }
         return validated;
     },
-    getURL(options) {
+    getURL(options, imageConfig) {
+        const defaults = imageConfig?.service?.config;
         const { src } = options;
         // An imported image's metadata, or another URL.
         if (!isImageUrl(src))
@@ -20,8 +24,8 @@ const imageService = {
             width: options.width,
             height: options.height,
             fit: fitOf(options.fit, options.width, options.height),
-            format: formatOf(options.format ?? "webp"),
-            quality: qualityOf(options.quality),
+            format: formatOf(options.format ?? defaults?.format ?? "webp"),
+            quality: qualityOf(options.quality ?? defaults?.quality),
         });
     },
 };

package/dist/astro-schema.d.ts

@@ -0,0 +1,20 @@
+import type * as Zod from "astro/zod";
+import type * as G from "./generated/types.gen.ts";
+import type { RichText } from "./types.ts";
+type Z = typeof Zod.z;
+type Schema = Zod.ZodType;
+export interface SchemaOptions {
+    /** Fields whose IDs the loader replaces with what they point at. */
+    expand: string[];
+    /** The rich text field that moves to `rendered`, out of the data. */
+    body: string | undefined;
+    richText: RichText;
+    /** Collection slugs by ID, for relations' targets. */
+    slugs: Map<string, string>;
+}
+/** The schema and the `Entry` type (a module, as Astro writes it) of the data. */
+export declare function collectionSchema(z: Z, collection: G.Collection, options: SchemaOptions): {
+    schema: Schema;
+    types: string;
+};
+export {};

package/dist/astro-schema.js

@@ -0,0 +1,125 @@
+/** The schema and the `Entry` type (a module, as Astro writes it) of the data. */
+export function collectionSchema(z, collection, options) {
+    const shape = {};
+    const lines = [];
+    for (const field of collection.fields) {
+        if (field.key === options.body)
+            continue;
+        const { schema, type, optional } = fieldSchema(z, field, options);
+        shape[field.key] = optional ? schema.optional() : schema;
+        const description = field.configuration.description;
+        const doc = `${field.name}${description ? `: ${description}` : ""}`;
+        lines.push(`  /** ${doc.replaceAll("*/", "*\\/")} */`, `  ${JSON.stringify(field.key)}${optional ? "?" : ""}: ${type}`);
+    }
+    const body = lines.join("\n");
+    const used = ["EmbeddedAsset", "EmbeddedRecord"].filter((name) => body.includes(name));
+    const types = [
+        `// The data of the ${collection.slug} collection's entries, from its fields in Nohead (@nohead/sdk/astro).`,
+        ...(used.length
+            ? [`import type { ${used.join(", ")} } from "@nohead/sdk/astro"`]
+            : []),
+        ``,
+        `export type Entry = {`,
+        ...lines,
+        `}`,
+        ``,
+    ].join("\n");
+    return { schema: z.object(shape), types };
+}
+function fieldSchema(z, field, { expand, richText, slugs }) {
+    const expanded = expand.includes(field.key);
+    let one;
+    switch (field.type) {
+        case "text":
+        case "long_text":
+            one = { schema: z.string(), type: "string" };
+            break;
+        case "rich_text":
+            one =
+                richText === "document"
+                    ? {
+                        schema: z.record(z.string(), z.unknown()),
+                        type: "Record<string, unknown>",
+                    }
+                    : { schema: z.string(), type: "string" };
+            break;
+        case "integer":
+            one = { schema: z.number().int(), type: "number" };
+            break;
+        case "decimal":
+            one = { schema: z.number(), type: "number" };
+            break;
+        case "date":
+            one = { schema: z.coerce.date(), type: "Date" };
+            break;
+        case "boolean":
+            // No value reads as false: it is never required.
+            return {
+                schema: z.boolean().default(false),
+                type: "boolean",
+                optional: false,
+            };
+        case "enum": {
+            const options = field.configuration.options;
+            one = {
+                schema: z.enum(options),
+                type: options.map((option) => JSON.stringify(option)).join(" | "),
+            };
+            break;
+        }
+        case "asset":
+            one = expanded
+                ? { schema: embeddedAsset(z), type: "EmbeddedAsset" }
+                : { schema: z.string(), type: "string" };
+            break;
+        case "relation": {
+            const target = slugs.get(field.configuration.target_collection_id);
+            one = expanded
+                ? { schema: embeddedRecord(z), type: "EmbeddedRecord" }
+                : target
+                    ? {
+                        schema: reference(z, target),
+                        type: `{ collection: ${JSON.stringify(target)}; id: string }`,
+                    }
+                    : { schema: z.string(), type: "string" };
+            break;
+        }
+        default:
+            one = { schema: z.unknown(), type: "unknown" };
+    }
+    if (field.multiple) {
+        const type = /[|{]/.test(one.type) ? `(${one.type})[]` : `${one.type}[]`;
+        return { schema: z.array(one.schema), type, optional: !field.required };
+    }
+    // An expanded asset or record deleted since (or unpublished) is left
+    // out, so it may be missing even when the field is required.
+    const optional = !field.required ||
+        (expanded && (field.type === "asset" || field.type === "relation"));
+    return { ...one, optional };
+}
+/**
+ * What Astro's `reference(collection)` makes of a record ID: a lookup for
+ * `getEntry`. Built here, since `astro:content` is Astro's virtual module.
+ */
+function reference(z, collection) {
+    return z.union([
+        z.string().transform((id) => ({ id, collection })),
+        z.object({ id: z.string(), collection: z.literal(collection) }),
+    ]);
+}
+function embeddedAsset(z) {
+    return z.object({
+        id: z.string(),
+        filename: z.string(),
+        content_type: z.string(),
+        alt: z.string().optional(),
+        width: z.number().optional(),
+        height: z.number().optional(),
+        image_url: z.string().optional(),
+        file_url: z.string().optional(),
+        media_url: z.string().optional(),
+    });
+}
+function embeddedRecord(z) {
+    return z.object({ id: z.string(), data: z.record(z.string(), z.unknown()) });
+}

package/dist/astro.d.ts

@@ -12,7 +12,8 @@
  *   }
  *
  * Every published record becomes an entry, by its record ID, when the site
- * builds (and when `astro dev` starts or syncs).
+ * builds (and when `astro dev` starts or syncs). On Astro 6 and later, the
+ * collection's fields give the entries their schema and TypeScript type.
  */
 import type { Loader } from "astro/loaders";
 import { type ClientOptions } from "./core.ts";

package/dist/astro.js

@@ -1,6 +1,7 @@
 import { Nohead } from "./client.js";
 import { environment } from "./core.js";
-import { NoheadError } from "./errors.js";
+import { collectionSchema } from "./astro-schema.js";
+import { AuthorizationError, NoheadError } from "./errors.js";
 /**
  * An Astro content loader for a Nohead collection. It reads the key from
  * `apiKey` or `NOHEAD_API_KEY`, and takes the other client options too
@@ -14,15 +15,49 @@ export function noheadLoader(options) {
     if (body && richText === "document") {
         throw new TypeError('noheadLoader renders its body from HTML or Markdown: set richText to "html" or "markdown"');
     }
+    const connect = () => {
+        // Astro reads .env into import.meta.env, not process.env.
+        if (!client.apiKey && !environment().NOHEAD_API_KEY) {
+            throw new NoheadError("Missing API key: pass `apiKey: import.meta.env.NOHEAD_API_KEY` to noheadLoader, or set NOHEAD_API_KEY in the environment");
+        }
+        return new Nohead({ ...client, richText });
+    };
     return {
         name: "nohead",
+        // Astro 6 and later: the entries' schema and type, from the collection's
+        // fields. A schema given to defineCollection takes its place.
+        async createSchema() {
+            const nohead = connect();
+            const { z } = await import("astro/zod");
+            try {
+                // Relations name their target by ID; references need its slug.
+                const slugsById = async () => {
+                    const slugs = new Map();
+                    for await (const each of nohead.collections.list()) {
+                        slugs.set(each.id, each.slug);
+                    }
+                    return slugs;
+                };
+                const [fields, slugs] = await Promise.all([
+                    nohead.collections.get(collection),
+                    slugsById(),
+                ]);
+                return collectionSchema(z, fields, {
+                    expand: expand ?? [],
+                    body,
+                    richText,
+                    slugs,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof AuthorizationError))
+                    throw error;
+                throw new NoheadError(`noheadLoader reads the ${collection} collection's fields for its schema, which takes the key's schema:read scope: add it, or pass a schema to defineCollection`, { cause: error });
+            }
+        },
         async load(context) {
             const { store, logger } = context;
-            // Astro reads .env into import.meta.env, not process.env.
-            if (!client.apiKey && !environment().NOHEAD_API_KEY) {
-                throw new NoheadError("Missing API key: pass `apiKey: import.meta.env.NOHEAD_API_KEY` to noheadLoader, or set NOHEAD_API_KEY in the environment");
-            }
-            const nohead = new Nohead({ ...client, richText });
+            const nohead = connect();
             const records = [];
             for await (const record of nohead.records.list(collection, {
                 limit: 100,

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.13.0";
+export declare const VERSION = "0.14.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.13.0";
+export const VERSION = "0.14.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",