@asteroidcms/core-utils 0.1.0 → 0.1.1

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:
 
@@ -244,7 +244,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 +255,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 +310,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 +348,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

@@ -324,6 +324,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",
@@ -1460,6 +1489,7 @@ exports.AsteroidCMSProvider = AsteroidCMSProvider;
 exports.RichTextContent = RichTextContent;
 exports.cmsImage = cmsImage;
 exports.createApolloClient = createApolloClient;
+exports.getContentReadTime = getContentReadTime;
 exports.parseRichText = parseRichText;
 exports.removeEmptyParagraphs = removeEmptyParagraphs;
 exports.useAsteroidCMSConfig = useAsteroidCMSConfig;