extract-cite 1.0.5 → 1.0.7

package/dist/full.d.ts

@@ -0,0 +1 @@
+export * from './index';

package/dist/html-to-cite/human-names-db.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Holder for the optional 92k human-names database.
+ *
+ * The default `extract-cite` entry ships without the ~1 MB names JSON so it
+ * stays slim. The database is used only to tell a person's name from an
+ * organization's; without it that check falls back to the word heuristics.
+ *
+ * Get it one of two ways:
+ * - import `extract-cite/full`, which bundles the JSON and registers it, or
+ * - call `loadHumanNamesDB()` to lazy-load it from a CDN at runtime.
+ */
+/** Lowercase name → 1 (first name) or 2 (last name). */
+export type HumanNamesDB = Record<string, number>;
+/** Published copy of the names JSON, served by jsDelivr from npm. */
+export declare const HUMAN_NAMES_DB_CDN_URL = "https://cdn.jsdelivr.net/npm/extract-cite/src/html-to-cite/human-names-92k.json";
+/** Registers a names database (or `null` to clear it). */
+export declare function setHumanNamesDB(db: HumanNamesDB | null): void;
+/** The registered names database, or `null` when none is loaded. */
+export declare function getHumanNamesDB(): HumanNamesDB | null;
+export interface LoadHumanNamesDBOptions {
+    /** Where to fetch the JSON from. Defaults to {@link HUMAN_NAMES_DB_CDN_URL}. */
+    url?: string;
+    /** Injectable fetch, for tests and non-browser runtimes. */
+    fetch?: typeof fetch;
+}
+/**
+ * Lazy-loads the names database from a CDN and registers it. Concurrent and
+ * repeat calls share one request; once loaded it resolves immediately.
+ * Resolves `null` (and leaves the slim fallback in place) if the fetch fails,
+ * so a CDN outage never breaks citation extraction.
+ */
+export declare function loadHumanNamesDB(options?: LoadHumanNamesDBOptions): Promise<HumanNamesDB | null>;

package/dist/index.d.ts

@@ -2,8 +2,10 @@
  * @fileoverview extract-cite: cite any webpage.
  *
  * - `extractCite` reads author, date, title and source straight off the HTML
- *   (meta tags, selectors, JSON-LD, URL, a 92k-name database). Instant, offline,
- *   partial.
+ *   (meta tags, selectors, JSON-LD, URL). Instant, offline, partial.
+ * - This default entry is slim: the 92k human-names database is not bundled.
+ *   Lazy-load it from a CDN with `loadHumanNamesDB()`, or import
+ *   `extract-cite/full`, which bundles it.
  * - `extractCiteLLM` then asks a model (OpenRouter by default) to finish the
  *   citation, score every part, flag the doubtful ones and read the authors'
  *   qualifications, and writes it as APA, MLA, Chicago, Harvard, IEEE and BibTeX.
@@ -11,4 +13,5 @@
 export * from './html-to-cite/extract-cite';
 export * from './html-to-cite/url-to-domain';
 export { extractHumanName } from './html-to-cite/human-names-recognize';
+export * from './html-to-cite/human-names-db';
 export * from './llm';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extract-cite",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "module": "./dist/extract-cite.es.js",
   "description": "Cite any webpage: regex/metadata extraction of author, date, title and source, plus an optional LLM pass (OpenRouter by default) that completes the APA parts, scores confidence per field, flags fields for review, extracts author qualifications, and formats APA, MLA, Chicago, Harvard, IEEE and BibTeX.",
   "author": "vtempest <grokthiscontact@gmail.com>",
@@ -18,6 +18,11 @@
       "import": "./dist/extract-cite.es.js",
       "require": "./dist/extract-cite.cjs.js"
     },
+    "./full": {
+      "types": "./dist/full.d.ts",
+      "import": "./dist/extract-cite-full.es.js",
+      "require": "./dist/extract-cite-full.cjs.js"
+    },
     "./*": {
       "types": "./src/*.ts",
       "import": "./src/*",

package/src/full.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview extract-cite/full: the same API as `extract-cite`, with the
+ * 92k human-names database bundled and registered on import, so person vs.
+ * organization detection works offline without `loadHumanNamesDB()`.
+ * Adds ~1 MB; prefer the default slim entry plus lazy loading in browsers.
+ */
+import dataHumanNames from "./html-to-cite/human-names-92k.json";
+import { setHumanNamesDB } from "./html-to-cite/human-names-db";
+
+setHumanNamesDB(dataHumanNames as Record<string, number>);
+
+export * from "./index";

package/src/html-to-cite/human-names-db.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Holder for the optional 92k human-names database.
+ *
+ * The default `extract-cite` entry ships without the ~1 MB names JSON so it
+ * stays slim. The database is used only to tell a person's name from an
+ * organization's; without it that check falls back to the word heuristics.
+ *
+ * Get it one of two ways:
+ * - import `extract-cite/full`, which bundles the JSON and registers it, or
+ * - call `loadHumanNamesDB()` to lazy-load it from a CDN at runtime.
+ */
+
+/** Lowercase name → 1 (first name) or 2 (last name). */
+export type HumanNamesDB = Record<string, number>;
+
+/** Published copy of the names JSON, served by jsDelivr from npm. */
+export const HUMAN_NAMES_DB_CDN_URL =
+  "https://cdn.jsdelivr.net/npm/extract-cite/src/html-to-cite/human-names-92k.json";
+
+let namesDB: HumanNamesDB | null = null;
+let loading: Promise<HumanNamesDB | null> | null = null;
+
+/** Registers a names database (or `null` to clear it). */
+export function setHumanNamesDB(db: HumanNamesDB | null): void {
+  namesDB = db;
+  loading = null;
+}
+
+/** The registered names database, or `null` when none is loaded. */
+export function getHumanNamesDB(): HumanNamesDB | null {
+  return namesDB;
+}
+
+export interface LoadHumanNamesDBOptions {
+  /** Where to fetch the JSON from. Defaults to {@link HUMAN_NAMES_DB_CDN_URL}. */
+  url?: string;
+  /** Injectable fetch, for tests and non-browser runtimes. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Lazy-loads the names database from a CDN and registers it. Concurrent and
+ * repeat calls share one request; once loaded it resolves immediately.
+ * Resolves `null` (and leaves the slim fallback in place) if the fetch fails,
+ * so a CDN outage never breaks citation extraction.
+ */
+export function loadHumanNamesDB(
+  options: LoadHumanNamesDBOptions = {}
+): Promise<HumanNamesDB | null> {
+  if (namesDB) return Promise.resolve(namesDB);
+  if (loading) return loading;
+
+  const { url = HUMAN_NAMES_DB_CDN_URL, fetch: fetchImpl = globalThis.fetch } =
+    options;
+
+  const request: Promise<HumanNamesDB | null> = Promise.resolve()
+    .then(() => fetchImpl(url))
+    .then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    })
+    .then((db: HumanNamesDB) => {
+      if (!db || typeof db !== "object") throw new Error("invalid names JSON");
+      namesDB = db;
+      return db;
+    })
+    .catch(() => null)
+    .finally(() => {
+      // A failed load is not cached, so a later call can retry.
+      if (loading === request) loading = null;
+    });
+  loading = request;
+  return request;
+}

package/src/html-to-cite/human-names-recognize.ts

@@ -1,8 +1,9 @@
 /**
  * @fileoverview Advanced human name recognition and normalization utility.
- * Distinguishes between person names and organizations using a 92k-entry name database.
+ * Distinguishes between person names and organizations using word heuristics,
+ * plus the 92k-entry name database when one is loaded (see human-names-db.ts).
  */
-import dataHumanNames from "./human-names-92k.json";
+import { getHumanNamesDB } from "./human-names-db";
 
 // Common organization terms for detection - extended list from provided code
 const TERMS_ORG =
@@ -381,13 +382,17 @@ function isOrganization(nameString) {
     return true;
   }
 
-  // Check if the name contains any human name parts according to our database
+  // Check if the name contains any human name parts according to our database.
+  // The slim build has no database loaded, so this check is skipped there.
+  // Database keys are lowercase, and so is every word here.
+  const dataHumanNames = getHumanNamesDB();
   let hasHumanNamePart = false;
-  for (const word of words) {
-    const nameTitle = word[0]?.toUpperCase() + word.slice(1)?.toLowerCase();
-    if (dataHumanNames[nameTitle] === 1 || dataHumanNames[nameTitle] === 2) {
-      hasHumanNamePart = true;
-      break;
+  if (dataHumanNames) {
+    for (const word of words) {
+      if (dataHumanNames[word] === 1 || dataHumanNames[word] === 2) {
+        hasHumanNamePart = true;
+        break;
+      }
     }
   }
 

package/src/index.ts

@@ -2,8 +2,10 @@
  * @fileoverview extract-cite: cite any webpage.
  *
  * - `extractCite` reads author, date, title and source straight off the HTML
- *   (meta tags, selectors, JSON-LD, URL, a 92k-name database). Instant, offline,
- *   partial.
+ *   (meta tags, selectors, JSON-LD, URL). Instant, offline, partial.
+ * - This default entry is slim: the 92k human-names database is not bundled.
+ *   Lazy-load it from a CDN with `loadHumanNamesDB()`, or import
+ *   `extract-cite/full`, which bundles it.
  * - `extractCiteLLM` then asks a model (OpenRouter by default) to finish the
  *   citation, score every part, flag the doubtful ones and read the authors'
  *   qualifications, and writes it as APA, MLA, Chicago, Harvard, IEEE and BibTeX.
@@ -11,4 +13,5 @@
 export * from "./html-to-cite/extract-cite";
 export * from "./html-to-cite/url-to-domain";
 export { extractHumanName } from "./html-to-cite/human-names-recognize";
+export * from "./html-to-cite/human-names-db";
 export * from "./llm";