@asteroidcms/core-utils 0.1.0 → 0.1.2

package/README.md

@@ -5,13 +5,13 @@
       <span>/core-utils</span>
     </div>
   </h1>
-  <p>Seamless integration utilities for <a href="https://cms.theasteroid.tech">Asteroid CMS</a> — a single React provider, Apollo client, content hooks, media helpers, and a rich-text renderer.</p>
+  <p>Seamless integration utilities for <a href="https://cms.theasteroid.tech">Asteroid CMS</a> - a single React provider, Apollo client, content hooks, media helpers, and a rich-text renderer.</p>
 </div>
 
-- **Provider-driven** — configure `cmsUrl`, `apiKey`, and Apollo behavior in one place
-- **API-key auth only** — sends `x-api-key` on every request, nothing else
-- **Typed hooks** — `useCmsContent` / `useCmsMutate` build GraphQL on the fly from a declarative selection
-- **Tree-shakeable** — ESM + CJS + types, `@apollo/client`/`react` as peer deps
+- **Provider-driven** - configure `cmsUrl`, `apiKey`, and Apollo behavior in one place
+- **API-key auth only** - sends `x-api-key` on every request, nothing else
+- **Typed hooks** - `useCmsContent` / `useCmsMutate` build GraphQL on the fly from a declarative selection
+- **Tree-shakeable** - ESM + CJS + types, `@apollo/client`/`react` as peer deps
 
 ---
 
@@ -82,15 +82,15 @@ function NewsList() {
 
 | Prop            | Type                           | Required | Default            | Description                                                  |
 | --------------- | ------------------------------ | -------- | ------------------ | ------------------------------------------------------------ |
-| `cmsUrl`        | `string`                       | ✓        | —                  | Base URL of the Asteroid CMS API.                            |
-| `apiKey`        | `string`                       | ✓        | —                  | Sent on every request as the `x-api-key` header.             |
+| `cmsUrl`        | `string`                       | ✓        | -                  | Base URL of the Asteroid CMS API.                            |
+| `apiKey`        | `string`                       | ✓        | -                  | Sent on every request as the `x-api-key` header.             |
 | `graphqlPath`   | `string`                       |          | `/graphql`         | Path appended to `cmsUrl` for the GraphQL endpoint.          |
 | `mediaPath`     | `string`                       |          | `/media/canonical` | Path used by `cmsImage` / `useCmsImage`.                     |
 | `headers`       | `Record<string, string>`       |          | `{}`               | Extra headers merged onto every GraphQL request.             |
-| `onError`       | `(error: unknown) => void`     |          | —                  | Called for each GraphQL / network / protocol error.          |
-| `cacheConfig`   | `InMemoryCacheConfig`          |          | —                  | Forwarded to `new InMemoryCache(...)` — e.g. `typePolicies`. |
-| `apolloOptions` | `Partial<ApolloClientOptions>` |          | —                  | Escape hatch — overrides any field on the Apollo client.     |
-| `client`        | `ApolloClient`                 |          | —                  | Bring your own pre-built client; skips the internal factory. |
+| `onError`       | `(error: unknown) => void`     |          | -                  | Called for each GraphQL / network / protocol error.          |
+| `cacheConfig`   | `InMemoryCacheConfig`          |          | -                  | Forwarded to `new InMemoryCache(...)` - e.g. `typePolicies`. |
+| `apolloOptions` | `Partial<ApolloClientOptions>` |          | -                  | Escape hatch - overrides any field on the Apollo client.     |
+| `client`        | `ApolloClient`                 |          | -                  | Bring your own pre-built client; skips the internal factory. |
 
 Example with everything wired:
 
@@ -195,6 +195,77 @@ const { data: topStories } = useCmsContent({
 
 ---
 
+## `fetchCmsContent` (Next.js / RSC)
+
+Server-side counterpart to `useCmsContent`. Use it in Next.js Server Components, route handlers, or any other server context. Accepts a server-side Apollo client plus the same options object as `useCmsContent`, and returns the resolved data directly.
+
+Pass a `getClient` function that returns a server-side Apollo client. The shape matches what `registerApolloClient` from `@apollo/client-integration-nextjs` already returns, so you can hand it through directly.
+
+```ts
+// app/lib/cms-server.ts
+import "server-only";
+import { ApolloClient, HttpLink, InMemoryCache } from "@apollo/client";
+import { registerApolloClient } from "@apollo/client-integration-nextjs";
+
+export const { getClient, query, PreloadQuery } = registerApolloClient(() => {
+  return new ApolloClient({
+    cache: new InMemoryCache(),
+    link: new HttpLink({
+      uri: `${process.env.CMS_API_BASE_URL}/graphql`,
+      headers: { "X-API-Key": process.env.CMS_X_API_KEY ?? "" },
+      fetchOptions: { next: { revalidate: 60, tags: ["cms:landing_page"] } },
+    }),
+  });
+});
+```
+
+```ts
+// app/news/[slug]/page.tsx
+import { fetchCmsContent } from "@asteroidcms/core-utils";
+import { getClient } from "@/app/lib/cms-server";
+
+// Single entry
+const article = await fetchCmsContent<Article>(getClient, {
+  schema_slug: "news",
+  entrySlug: params.slug,
+  fullData: true,
+});
+
+// List
+const articles = await fetchCmsContent<Article[]>(getClient, {
+  schema_slug: "news",
+  limit: 10,
+  status: "PUBLISHED",
+  select: ["title", "slug", "publish_date"],
+});
+```
+
+Outside Next.js you can pass any `() => ApolloClient` - e.g. `() => createApolloClient({ cmsUrl, apiKey })`.
+
+Add `import "server-only"` in the file that calls it if you want Next.js to fail the build when it leaks into a client component.
+
+---
+
+## `buildCmsQuery`
+
+Lower-level helper that turns a declarative selection into a GraphQL `DocumentNode` plus variables. Used internally by `useCmsContent` and `fetchCmsContent`; exported so you can drive your own Apollo calls (cache reads, prefetching, batching, etc.).
+
+```ts
+import { buildCmsQuery } from "@asteroidcms/core-utils";
+
+const { query, variables, isSingle } = buildCmsQuery({
+  schema_slug: "news",
+  limit: 10,
+  status: "PUBLISHED",
+  select: ["title", "slug"],
+});
+
+const { data } = await apolloClient.query({ query, variables });
+const entries = isSingle ? data.entry : data.entries;
+```
+
+---
+
 ## `useCmsMutate`
 
 `create` / `update` / `delete` against a schema, with the same selection syntax.
@@ -244,7 +315,7 @@ removeComment();
 Build a canonical media URL for an asset id.
 
 ```tsx
-// Inside React — preferred
+// Inside React - preferred
 const cmsImage = useCmsImage();
 <img src={cmsImage(article.cover_image)} alt="" />;
 
@@ -255,6 +326,34 @@ cmsImage(id, { cmsUrl: "https://cms-api.example.com" });
 
 ---
 
+## `getContentReadTime`
+
+Estimate reading time for a string of content (plain text or HTML). Strips tags, decodes common entities, counts words, and formats the result.
+
+```ts
+import { getContentReadTime } from "@asteroidcms/core-utils";
+
+getContentReadTime(article.body);
+// "3 min read"
+
+getContentReadTime(article.body, {
+  wordsPerMinute: 220,
+  format: "long",
+  round: "round",
+  minMinutes: 1,
+});
+// "3 minutes read"
+```
+
+| Option           | Type                            | Default   | Description                                       |
+| ---------------- | ------------------------------- | --------- | ------------------------------------------------- |
+| `wordsPerMinute` | `number`                        | `200`     | Average reading speed.                            |
+| `format`         | `"short" \| "long"`             | `"short"` | `"3 min read"` vs `"3 minutes read"`.             |
+| `round`          | `"ceil" \| "round" \| "floor"`  | `"ceil"`  | How fractional minutes are rounded.               |
+| `minMinutes`     | `number`                        | `1`       | Floor for the returned value.                     |
+
+---
+
 ## `<RichTextContent>`
 
 Render Asteroid CMS rich-text JSON/HTML with syntax-highlighted code blocks (via `highlight.js`).
@@ -282,7 +381,7 @@ const html = parseRichText(article.body, {
 
 ---
 
-## Advanced — bring your own Apollo client
+## Advanced - bring your own Apollo client
 
 ```tsx
 import { ApolloClient, InMemoryCache } from "@apollo/client";
@@ -320,8 +419,8 @@ npm run build      # writes dist/index.js, dist/index.cjs, dist/index.d.ts
 
 ## License
 
-Proprietary — Copyright © Asteroid. All rights reserved.
+Proprietary - Copyright © Asteroid. All rights reserved.
 
 This package is licensed for use only; copying, modifying, or
-redistributing the source — in whole or in part — is not permitted.
+redistributing the source - in whole or in part - is not permitted.
 See [LICENSE](./LICENSE) for the full terms.

package/dist/index.cjs

@@ -119,7 +119,7 @@ function useCmsContent({
   variables = {}
 }) {
   const isSingle = !!entrySlug;
-  const buildSelection = (items = []) => {
+  const buildSelection2 = (items = []) => {
     const lines = [];
     items.forEach((item) => {
       if (typeof item === "string") {
@@ -132,7 +132,7 @@ function useCmsContent({
         }
         const alias = item.as || item.field;
         const resolver = item.single ? "expandedReferenceObject" : "expandedReference";
-        const subSelection = item.select?.length ? buildSelection(item.select) : "data { ... }";
+        const subSelection = item.select?.length ? buildSelection2(item.select) : "data { ... }";
         lines.push(`
           ${alias}: ${resolver}(slug: "${item.field}") {
             ${subSelection}
@@ -145,7 +145,7 @@ function useCmsContent({
   const selectionParts = [];
   if (fullData) selectionParts.push("data");
   if (select.length > 0) {
-    const userSelection = buildSelection(select);
+    const userSelection = buildSelection2(select);
     if (userSelection) selectionParts.push(userSelection);
   }
   const selection = selectionParts.join("\n      ").trim() || "id";
@@ -229,7 +229,7 @@ function useCmsMutate({
   entryId,
   variables: inputVariables = {}
 }) {
-  const buildSelection = (items = []) => {
+  const buildSelection2 = (items = []) => {
     const lines = [];
     for (const item of items) {
       if (typeof item === "string") {
@@ -243,7 +243,7 @@ function useCmsMutate({
         continue;
       }
       const resolver = single ? "expandedReferenceObject" : "expandedReference";
-      const sub = buildSelection(subSelect) || "id slug";
+      const sub = buildSelection2(subSelect) || "id slug";
       lines.push(`
         ${alias}: ${resolver}(slug: "${field}") {
           id
@@ -254,7 +254,7 @@ function useCmsMutate({
     }
     return lines.join("\n      ").trim();
   };
-  const userSelection = buildSelection(select);
+  const userSelection = buildSelection2(select);
   let selection = fullData ? "data" : "";
   if (userSelection) {
     selection = selection ? `${selection}
@@ -311,6 +311,129 @@ function useCmsMutate({
     data: resultData
   };
 }
+function buildSelection(items = []) {
+  const lines = [];
+  items.forEach((item) => {
+    if (typeof item === "string") {
+      lines.push(`${item}: dataField(slug: "${item}")`);
+      return;
+    }
+    if ("field" in item && typeof item.field === "string") {
+      if (!("select" in item)) {
+        const alias2 = item.as || item.field;
+        lines.push(`${alias2}: dataField(slug: "${item.field}")`);
+        return;
+      }
+      const alias = item.as || item.field;
+      const resolver = item.single ? "expandedReferenceObject" : "expandedReference";
+      const subSelection = item.select?.length ? buildSelection(item.select) : "data { ... }";
+      lines.push(`
+        ${alias}: ${resolver}(slug: "${item.field}") {
+          ${subSelection}
+        }
+      `);
+    }
+  });
+  return lines.join("\n      ").trim();
+}
+function buildCmsQuery({
+  schema_slug,
+  entrySlug,
+  select = [],
+  fullData = false,
+  limit,
+  offset,
+  status = "PUBLISHED",
+  filter,
+  search,
+  variables = {}
+}) {
+  const isSingle = Boolean(entrySlug);
+  const selectionParts = [];
+  if (fullData) {
+    selectionParts.push("data");
+  }
+  if (select.length > 0) {
+    const userSelection = buildSelection(select);
+    if (userSelection) {
+      selectionParts.push(userSelection);
+    }
+  }
+  const selection = selectionParts.join("\n      ").trim() || "id";
+  const queryVariables = {
+    schema_slug,
+    ...entrySlug && { slug: entrySlug },
+    ...variables
+  };
+  const fieldArgParts = ["schema_slug: $schema_slug"];
+  if (!isSingle) {
+    if (typeof limit === "number" && limit >= 0) {
+      fieldArgParts.push("limit: $limit");
+      queryVariables.limit = limit;
+    }
+    if (typeof offset === "number" && offset >= 0) {
+      fieldArgParts.push("offset: $offset");
+      queryVariables.offset = offset;
+    }
+    if (status) {
+      const statuses = status;
+      if (statuses.length > 0) {
+        fieldArgParts.push("status: $status");
+        queryVariables.status = statuses;
+      }
+    }
+    const hasSearch = Array.isArray(search) && search.length > 0;
+    const hasFilter = filter && typeof filter === "object" && Object.keys(filter).length > 0;
+    if (hasSearch || hasFilter) {
+      const mergedFilter = hasFilter ? { ...filter } : {};
+      if (hasSearch) {
+        for (const condition of search) {
+          mergedFilter[condition.field] = {
+            regex: true,
+            value: condition.value,
+            mode: condition.mode ?? "i"
+          };
+        }
+      }
+      fieldArgParts.push("data: $filter");
+      queryVariables.filter = mergedFilter;
+    }
+  }
+  const varDecls = ["$schema_slug: String!"];
+  if ("limit" in queryVariables) varDecls.push("$limit: Float");
+  if ("offset" in queryVariables) varDecls.push("$offset: Float");
+  if ("status" in queryVariables) varDecls.push("$status: ContentStatus");
+  if ("filter" in queryVariables) varDecls.push("$filter: JSONObject");
+  const varBlock = varDecls.length > 0 ? `(
+  ${varDecls.join("\n  ")}
+)` : "";
+  const contentFieldArgs = fieldArgParts.join(", ");
+  const queryStr = isSingle ? `
+      query Get${schema_slug}Entry($schema_slug: String!, $slug: String!) {
+        entry: contentEntry(schema_slug: $schema_slug, slug: $slug) {
+          ${selection}
+        }
+      }
+    ` : `
+      query Get${schema_slug}Entries${varBlock} {
+        entries: contentEntries(${contentFieldArgs}) {
+          ${selection}
+        }
+      }
+    `;
+  return {
+    query: client.gql(queryStr),
+    variables: queryVariables,
+    isSingle
+  };
+}
+
+// src/fetchCmsContent.ts
+async function fetchCmsContent(getClient, opts) {
+  const { query, variables, isSingle } = buildCmsQuery(opts);
+  const { data } = await getClient().query({ query, variables });
+  return isSingle ? data.entry : data.entries;
+}
 
 // src/utils/cmsImage.ts
 function cmsImage(id, options) {
@@ -324,6 +447,35 @@ function useCmsImage() {
   return (id) => cmsImage(id, { cmsUrl, mediaPath });
 }
 
+// src/utils/getContentReadTime.ts
+function getContentReadTime(content, options = {}) {
+  const {
+    wordsPerMinute = 200,
+    format = "short",
+    round = "ceil",
+    minMinutes = 1
+  } = options;
+  if (!content || typeof content !== "string") {
+    return format === "short" ? `${minMinutes} min read` : `${minMinutes} minute read`;
+  }
+  let text = content.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ");
+  text = text.replace(/<\/(p|div|h[1-6]|li|blockquote|pre|code|br|tr)>/gi, " ").replace(/<[^>]+>/g, " ");
+  text = text.replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&#39;/gi, "'").replace(/&quot;/gi, '"');
+  text = text.replace(/\s+/g, " ").trim();
+  const words = text.split(" ").filter(Boolean).length;
+  const rawMinutes = words / wordsPerMinute;
+  const roundMap = {
+    ceil: Math.ceil,
+    round: Math.round,
+    floor: Math.floor
+  };
+  const minutes = Math.max(minMinutes, roundMap[round](rawMinutes));
+  if (format === "long") {
+    return `${minutes} ${minutes === 1 ? "minute" : "minutes"} read`;
+  }
+  return `${minutes} min read`;
+}
+
 // src/components/richTextParser.ts
 var DEFAULT_ALLOWLIST = [
   "p",
@@ -1458,8 +1610,11 @@ function RichTextContent({
 
 exports.AsteroidCMSProvider = AsteroidCMSProvider;
 exports.RichTextContent = RichTextContent;
+exports.buildCmsQuery = buildCmsQuery;
 exports.cmsImage = cmsImage;
 exports.createApolloClient = createApolloClient;
+exports.fetchCmsContent = fetchCmsContent;
+exports.getContentReadTime = getContentReadTime;
 exports.parseRichText = parseRichText;
 exports.removeEmptyParagraphs = removeEmptyParagraphs;
 exports.useAsteroidCMSConfig = useAsteroidCMSConfig;