astro-relatinator 3.0.0 → 3.0.1

package/README.md

@@ -160,11 +160,50 @@ const related = await getEmDashRelated("posts", post, { limit: 3 });
 </ul>
 ```
 
-The result has the same type as the entry that you give. When you give an id, the type of `entry.data` is `Record<string, unknown>`. To set a different type, use `getEmDashRelated<typeof post>("posts", "my-slug")`.
+The result contains the published entries from the collection, not copies of the entry that you give. The types are:
+
+```ts
+interface EmDashEntry<D extends object = Record<string, unknown>> {
+  readonly id: string;
+  readonly data: D;
+}
+
+function getEmDashRelated<D extends object = Record<string, unknown>>(
+  collection: string,
+  entry: string | EmDashEntry<D> | EmDashEntry<Partial<D>>,
+  options?: GetEmDashRelatedOptions<D>
+): Promise<EmDashEntry<D>[]>;
+```
+
+`D` is the type of `entry.data` in the published entries. When you give an entry object, TypeScript gets `D` from the type of its `data`. When you give an id, `D` is `Record<string, unknown>`.
+
+To set `D`, give it as a type argument. Then the entry object can have only some of the keys of `D`. The result has all of the keys of `D`, so you can map it without a cast:
+
+```ts
+interface PostData {
+  title: string;
+  excerpt: string;
+  author: string;
+  content: unknown[];
+}
+
+// Only some of the keys of PostData.
+const { title, excerpt, content } = post.data;
+const entry = { id: post.id, data: { title, excerpt, content } };
+const related = await getEmDashRelated<PostData>("posts", entry, { limit: 3 });
+
+const cards = related.map(({ id, data }) => ({
+  href: `/posts/${id}`,
+  title: data.title,
+  author: data.author,
+}));
+```
 
 ### EmDash options
 
-The options are the same as for `getRelated()`: `limit` (default `5`), `method` (default `"bm25"`), `fields`, and `text`.
+The options are the same as for `getRelated()`: `limit` (default `5`), `method` (default `"bm25"`), `fields`, and `text`. The `GetEmDashRelatedOptions<D>` type describes them.
+
+The `text` function gets each published entry. It also gets the entry object that you give when its id is not in the published entries. Thus the type of its argument is `EmDashEntry<Partial<D>>`, and each key of `entry.data` can be `undefined`.
 
 The default text of an entry has two parts:
 

package/dist/emdash.d.ts

@@ -1,17 +1,23 @@
-import type { ContentEntry } from "./entry-text.js";
 import { portableTextToPlainText } from "./portable-text.js";
 import { type RelatedOptions } from "./related-index.js";
 export { portableTextToPlainText };
-/** The entry type when `getEmDashRelated` gets an id. */
-export interface EmDashEntry {
+/**
+ * An EmDash entry. `D` is the type of `data` in the published entries
+ * of the collection.
+ */
+export interface EmDashEntry<D extends object = Record<string, unknown>> {
     readonly id: string;
-    readonly data: Record<string, unknown>;
+    readonly data: D;
 }
-export type GetEmDashRelatedOptions<E> = RelatedOptions<E>;
+/**
+ * `text` gets the published entries and, for an entry object that is not
+ * published, that object. Thus its data is a part of `D`.
+ */
+export type GetEmDashRelatedOptions<D extends object = Record<string, unknown>> = RelatedOptions<EmDashEntry<Partial<D>>>;
 /**
  * Finds the published entries of an EmDash `collection` that are most
  * related to `entry`, in rank order. The model is built once and reused
- * until an entry changes.
+ * until an entry changes. `D` is the type of `data` in the published
+ * entries. An entry object can have only a part of `D`.
  */
-export declare function getEmDashRelated<E extends ContentEntry>(collection: string, entry: E, options?: GetEmDashRelatedOptions<E>): Promise<E[]>;
-export declare function getEmDashRelated<E extends ContentEntry = EmDashEntry>(collection: string, entry: string, options?: GetEmDashRelatedOptions<E>): Promise<E[]>;
+export declare function getEmDashRelated<D extends object = Record<string, unknown>>(collection: string, entry: string | EmDashEntry<D> | EmDashEntry<Partial<D>>, options?: GetEmDashRelatedOptions<D>): Promise<EmDashEntry<D>[]>;

package/dist/emdash.js

@@ -22,7 +22,15 @@ async function getPublishedEntries(collection) {
     } while (cursor);
     return entries;
 }
-export async function getEmDashRelated(collection, entry, options = {}) {
+/**
+ * Finds the published entries of an EmDash `collection` that are most
+ * related to `entry`, in rank order. The model is built once and reused
+ * until an entry changes. `D` is the type of `data` in the published
+ * entries. An entry object can have only a part of `D`.
+ */
+export async function getEmDashRelated(collection, 
+// `EmDashEntry<D>` makes inference keep the optional keys of `D`.
+entry, options = {}) {
     const { text, fields } = options;
     const textOf = text ?? ((e) => emdashEntryText(e, fields));
     const index = relatedIndex({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-relatinator",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Find related entries in your Astro content collections",
   "author": "Darko Bozhinovski <dbozhinovski@gmail.com>",
   "license": "MIT",