storyloco 2.2.0 → 2.3.0

package/README.md

@@ -176,10 +176,19 @@ await storyblok.story('layout')
 // A list. `total` is the unpaged count, for "showing n of m"
 const { stories, total } = await storyblok.stories({ content_type: 'blog', per_page: 2 })
 
+// Everything that matches, paged through the API's 100-per-page cap
+const products = await storyblok.all({ content_type: 'product' })
+
 // The link tree, flattened — Storyblok returns it keyed by uuid
 const links = await storyblok.links({ starts_with: 'blog/' })
 ```
 
+Reads with a `content_type` are typed from your generated schema: the plugin registers
+the space's content types with storyloco, so `stories({ content_type: 'product' })` yields
+product stories and `content_type: 'product,category'` a union of both — no type argument
+needed. Until a schema has been generated, or for a name it doesn't know, the content falls
+back to the SDK's permissive type. An explicit type argument always wins.
+
 Your params are spread last, so any default can be overridden:
 
 ```typescript
@@ -194,6 +203,18 @@ const product = await storyblok.find<Product>(`products/${slug}`)
 if (!product) error(404, 'Product not found')
 ```
 
+The content type can be a union. Each member becomes its own story type, so `is_component`
+can narrow the result — checking `story.content.component` yourself narrows only `content`,
+not the story:
+
+```typescript
+import { is_component } from 'storyloco'
+
+const story = await storyblok.find<Product | Category>(`products/${slug}`)
+if (is_component(story, 'product')) story.content.sku // ISbStoryData<Product>
+if (is_component(story, 'category')) story.content.description // ISbStoryData<Category>
+```
+
 It's callable too, for anything the methods don't cover:
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "storyloco",
-	"version": "2.2.0",
+	"version": "2.3.0",
 	"description": "A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, and Tailwind CSS",
 	"keywords": [
 		"storyblok",

package/packages/vite/dist/schema/plugin.js

@@ -218,6 +218,11 @@ import type { ISbStoryData } from '@storyblok/js';`, "");
 			               }
 
 			               export type ContentType = ContentTypes[keyof ContentTypes]
+
+			               /** Lets storyloco type reads by \`content_type\` without a type argument. */
+			               declare module "storyloco" {
+			                 interface Registry extends ContentTypes {}
+			               }
 			             `;
             let content = component_types.replace(`// This file was generated by the storyblok CLI.
 // DO NOT MODIFY THIS FILE BY HAND.`, header);

package/packages/vite/dist/server.d.ts

@@ -1,6 +1,6 @@
-import type { ISbStoriesParams, ISbStoryData, ISbStoryParams } from "@storyblok/svelte";
+import type { ISbStoriesParams, ISbStoryParams } from "@storyblok/svelte";
 import type { ISbLink, ISbLinksParams } from "storyblok-js-client";
-import { type StoryblokClient, type Version } from "./storyblok.svelte.js";
+import { type ContentFor, type Story, type StoryblokClient, type Version } from "./storyblok.svelte.js";
 /** The content version for the current request, as set by the `version` hook. */
 export declare function version(): Version;
 /**
@@ -20,7 +20,9 @@ export declare function version(): Version;
  * // anywhere on the server
  * await storyblok.story("layout")
  * await storyblok.find<Product>(`products/${slug}`) // null when missing
- * await storyblok.stories<Blog>({ content_type: "blog", per_page: 2 })
+ * await storyblok.find<Product | Category>(slug) // a union of stories; narrow with is_component
+ * await storyblok.stories({ content_type: "blog", per_page: 2 }) // typed from the generated schema
+ * await storyblok.all<Product>({ content_type: "product" }) // every page
  *
  * const { client, version } = storyblok()
  * await client.get("cdn/links", { version })
@@ -32,18 +34,35 @@ export declare function setup(client: StoryblokClient): (() => {
 }) & {
     story: <T = import("storyblok-js-client").ISbComponentType<string> & {
         [index: string]: any;
-    }>(slug: string, params?: ISbStoryParams) => Promise<ISbStoryData<T>>;
+    }>(slug: string, params?: ISbStoryParams) => Promise<Story<T>>;
     find: <T = import("storyblok-js-client").ISbComponentType<string> & {
         [index: string]: any;
-    }>(slug: string, params?: ISbStoryParams) => Promise<ISbStoryData<T> | null>;
+    }>(slug: string, params?: ISbStoryParams) => Promise<Story<T> | null>;
+    stories: {
+        <K extends string>(params: ISbStoriesParams & {
+            content_type: K;
+        }): Promise<{
+            stories: Story<ContentFor<K>>[];
+            total: number;
+        }>;
+        <T = import("storyblok-js-client").ISbComponentType<string> & {
+            [index: string]: any;
+        }>(params?: ISbStoriesParams): Promise<{
+            stories: Story<T>[];
+            total: number;
+        }>;
+    };
+    all: {
+        <K extends string>(params: ISbStoriesParams & {
+            content_type: K;
+        }): Promise<Array<Story<ContentFor<K>>>>;
+        <T = import("storyblok-js-client").ISbComponentType<string> & {
+            [index: string]: any;
+        }>(params?: ISbStoriesParams): Promise<Array<Story<T>>>;
+    };
     /**
      * The link tree as a flat array — Storyblok returns it keyed by uuid, which is
      * almost never what you want. Filtering and ordering are left to the caller.
      */
     links(params?: ISbLinksParams): Promise<ISbLink[]>;
-    /** A list of stories. `total` is the unpaged count, for "showing n of m". */
-    stories<T>(params?: ISbStoriesParams): Promise<{
-        stories: Array<ISbStoryData<T>>;
-        total: number;
-    }>;
 };

package/packages/vite/dist/server.js

@@ -1,6 +1,6 @@
 import { getRequestEvent } from "$app/server";
 import { error } from "@sveltejs/kit";
-import { handle_error } from "./storyblok.svelte.js";
+import { handle_error, } from "./storyblok.svelte.js";
 function is_not_found(err) {
     return typeof err === "object" && err !== null && "status" in err && err.status === 404;
 }
@@ -25,7 +25,9 @@ export function version() {
  * // anywhere on the server
  * await storyblok.story("layout")
  * await storyblok.find<Product>(`products/${slug}`) // null when missing
- * await storyblok.stories<Blog>({ content_type: "blog", per_page: 2 })
+ * await storyblok.find<Product | Category>(slug) // a union of stories; narrow with is_component
+ * await storyblok.stories({ content_type: "blog", per_page: 2 }) // typed from the generated schema
+ * await storyblok.all<Product>({ content_type: "product" }) // every page
  *
  * const { client, version } = storyblok()
  * await client.get("cdn/links", { version })
@@ -61,9 +63,33 @@ export function setup(client) {
             error(404, "Story not found");
         return found;
     }
+    async function stories(params = {}) {
+        const response = await client
+            .get("cdn/stories", {
+            version: version(),
+            resolve_links: "url",
+            resolve_assets: 1,
+            ...params,
+        })
+            .catch(handle_error);
+        return { stories: response.data.stories, total: response.total ?? 0 };
+    }
+    async function all(params = {}) {
+        return client
+            .getAll("cdn/stories", {
+            version: version(),
+            resolve_links: "url",
+            resolve_assets: 1,
+            per_page: 100,
+            ...params,
+        })
+            .catch(handle_error);
+    }
     return Object.assign(context, {
         story,
         find,
+        stories,
+        all,
         /**
          * The link tree as a flat array — Storyblok returns it keyed by uuid, which is
          * almost never what you want. Filtering and ordering are left to the caller.
@@ -74,20 +100,5 @@ export function setup(client) {
                 .catch(handle_error);
             return Object.values(response.data.links ?? {});
         },
-        /** A list of stories. `total` is the unpaged count, for "showing n of m". */
-        async stories(params = {}) {
-            const response = await client
-                .get("cdn/stories", {
-                version: version(),
-                resolve_links: "url",
-                resolve_assets: 1,
-                ...params,
-            })
-                .catch(handle_error);
-            return {
-                stories: response.data.stories,
-                total: response.total ?? 0,
-            };
-        },
     });
 }

package/packages/vite/dist/storyblok.svelte.d.ts

@@ -140,6 +140,46 @@ export interface Richtext<Blocks = unknown> {
     content?: Array<Richtext<Blocks>>;
     marks?: Array<Richtext<Blocks>>;
 }
+/**
+ * Content types by component name, for narrowing reads by `content_type`. Empty here;
+ * the schema plugin's generated file merges the space's `ContentTypes` into it, so
+ * `storyblok.stories({ content_type: "product" })` is typed as products without a type
+ * argument. Until a schema is generated every name falls back to the SDK's content type.
+ */
+export interface Registry {
+}
+/** The SDK's permissive content type: any component, any fields. */
+export type Content = ISbStoryData["content"];
+/** Each name in a comma-separated `content_type`. */
+type Names<S extends string> = S extends `${infer A},${infer B}` ? A | Names<B> : S;
+/**
+ * The content behind a `content_type` param. Registered names map to their generated
+ * types (a list to their union); anything else is the permissive `Content`.
+ */
+export type ContentFor<K extends string> = [Names<K>] extends [keyof Registry] ? Registry[Names<K>] : Content;
+/**
+ * A story per member of `T`, so a union of content types is a union of stories —
+ * `Story<Product | Category>` is `ISbStoryData<Product> | ISbStoryData<Category>`, which
+ * `is_component` can narrow. `ISbStoryData<Product | Category>` can't be.
+ */
+export type Story<T> = T extends unknown ? ISbStoryData<T> : never;
+/**
+ * Narrow a story (or a union of them) by its content's `component`. TypeScript won't
+ * narrow the story through the nested discriminant on its own.
+ *
+ * @example
+ * ```ts
+ * const story = await storyblok.find<Product | Category>(`products/${slug}`)
+ * if (is_component(story, "product")) story.content.sku // ISbStoryData<Product>
+ * ```
+ */
+export declare function is_component<S extends ISbStoryData<{
+    component?: string;
+}>, K extends string>(story: S | null | undefined, component: K): story is Extract<S, {
+    content: {
+        component?: K;
+    };
+}>;
 /** Adds the `story.url` that `resolve_links: "url"` injects but the CLI doesn't declare. */
 export type Resolved<T extends {
     story?: unknown;

package/packages/vite/dist/storyblok.svelte.js

@@ -137,6 +137,19 @@ export class StoryblokClient {
         };
     }
 }
+/**
+ * Narrow a story (or a union of them) by its content's `component`. TypeScript won't
+ * narrow the story through the nested discriminant on its own.
+ *
+ * @example
+ * ```ts
+ * const story = await storyblok.find<Product | Category>(`products/${slug}`)
+ * if (is_component(story, "product")) story.content.sku // ISbStoryData<Product>
+ * ```
+ */
+export function is_component(story, component) {
+    return story?.content.component === component;
+}
 /**
  * Resolve a multilink to an href. Story links become root-relative, everything else passes
  * through. Prefers `story.url` over `cached_url`, which goes stale when a target moves —