media-synopsis 0.1.1 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Thomas Geraghty
+Copyright (c) 2014-2026 Thomas Geraghty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,70 +1,75 @@
-Media Synopsis
-==============
+# Media Synopsis
 
-Media Synopsis lets you get a synopsis for books, movies, video games, anime and more.
+Media Synopsis returns a short synopsis for a movie, book, anime, video game, or other media title. It reads the lead section of the matching English Wikipedia article and cleans it up for display.
 
-Installation
-------------
+Requires Node.js 20 or newer.
 
-`npm install media-synopsis`
+## Installation
 
-Usage
------
+```bash
+npm install media-synopsis
+```
+
+## Usage
+
+The package is an ES module.
 
 ```javascript
-var synopsis = require('media-synopsis').synopsis;
-
-synopsis('beyblade', ['anime', 'Japanese animated'], function(err, text) {
-    if (err) {
-        console.log(err);
-        return;
-    }
-    console.log(text.title +
-        '\n=======================================\n\n' +
-        text.content);
-});
-```
+import { synopsis } from 'media-synopsis';
 
+const text = await synopsis('beyblade', ['anime', 'Japanese animated']);
+console.log(text.title +
+    '\n=======================================\n\n' +
+    text.content);
+```
 
-Prints:
+Prints something like:
 
 ```markdown
 Beyblade
 =======================================
 
-Beyblade, known in Japan as Explosive Shoot Beyblade ( Bakuten Shūto Beiburēdo?), is a Japanese manga series written and illustrated by Takao Aoki in order to promote sales of spinning tops called "Beyblades". Originally serialized in CoroCoro Comic from January, 2000 to December, 2003, the individual chapters were collected and published in 14 tankōbon by Shogakukan. The series focuses on a group of kids who form teams with which they battle one another using Beyblades.
-
-The manga is licensed for English language release in North America by Viz Media. An anime adaptation, also titled Beyblade and spanning 51 episodes, aired in Japan on TV Tokyo from January 8, 2001 to December 24, 2001. The second, Beyblade V-Force, ran for another 51 episodes from January 7, 2002 until December 30, 2002. Beyblade G-Revolution, the third and final adaptation, also spanned 52 episodes (the last two episodes were released together as a double-length special in Japan) and aired from January 6, 2003, until its conclusion on December 28, 2003. Nelvana licensed the anime for an English-language release. Takara Tomy also developed the Beyblade toy line.
+Beyblade, known in Japan as Bakuten Shoot Beyblade, is a Japanese manga series written and illustrated by Takao Aoki, created to promote Takara's Beyblade spinning tops. The series focuses on a group of kids who form teams, which battle one another using Beyblades. It was serialized in Shogakukan's children's manga magazine CoroCoro Comic from August 1999 to June 2004, with its chapters collected and published in 14 tankōbon volumes. It was licensed for English release in North America by Viz Media and in Singapore, Australia and New Zealand by Chuang Yi.
 
-Source: [Wikipedia](http://en.wikipedia.org/wiki/Beyblade)
+An anime adaptation by Madhouse aired in Japan on TV Tokyo from January to December 2001 and was followed by two sequel series, Beyblade V-Force and Beyblade G-Revolution, and the 2002 film Beyblade: Fierce Battle all three by Nippon Animedia, a partnership between Nippon Animation, Takara, Agatsuma and Epoch. Nelvana licensed and produced English-language adaptations of the anime series and the film.
 
+Source: [Wikipedia](https://en.wikipedia.org/wiki/Beyblade_(manga))
 ```
-How it works?
--------------
 
-Media Synopsis takes the first Google result for mediaTitle + first provided mediaType + site:wikipedia.org. So for the example above it gets the first Google result for 'beyblade anime site:wikipedia.org'.
+The wording comes from the current Wikipedia article, so it will change as that article changes.
 
-It then visits the Wikipedia page and attempts to get a synopsis for the media types you provided. Since the Wikipedia page may not be just the media you're looking for, it checks the first 4 paragraphs for your media types. If none of them are found, or you didn't provide any then only the first paragraph is returned. If they are found, then every paragraph from the first to the one where they were found inclusive will be returned.
+## How it works
 
-This library was written to be used for generating placeholder text on a media collector's site before being replaced with real content. Linking back to Wikipedia as the source makes it nice and legal too so you might mind it useful if you want to try and provide feedback to the user that the title they're typing for a piece of media is correct.
+`synopsis` searches the English Wikipedia API for the media title plus the first media type you passed. For the example above, the search is `beyblade anime`. It takes the first result and reads that page's lead section as plain text.
 
-This library has one other use: Auto-correcting media names based on the title of the Wikipedia article. This may be of limited usefulness but it's incredibly good for getting widely accepted titles for Japanese Anime (e.g. 'mahouka' returns 'The Irregular at Magic High School').
+The lead is split into paragraphs. The first four are checked for any of the media types you provided. If one of those paragraphs mentions a type, every paragraph from the start through that one is kept. If none of them match, or you did not pass any types, only the first paragraph is kept.
 
-API
----
+The page title is cleaned up for use as a display name. A Wikipedia suffix is removed, `List of X episodes` becomes `X`, and a trailing disambiguator such as `(film)` or `(manga)` is removed. That last part is what turns a loose query such as `mahouka` into `The Irregular at Magic High School`.
 
-###`synopsis(mediaTitle, [mediaTypes], callback)`
+The synopsis text drops Japanese and Hepburn pronunciation parentheses, and bracketed citation markers such as `[1]`. A Markdown link to the Wikipedia article is appended. Linking back to Wikipedia is what makes the placeholder text reasonable to show while a real description is still missing.
 
-mediaTitle is a string, mediaTypes is an array of strings, or alternatively if there is only one a string can be provided. Callback is a function that should take two params: error and response.
+## API
 
-Returns an object with a `title` and `content` property. The `title` is a cleaned up Wikipedia title for the page, with things like ' - Wikipedia, the free encyclopedia' and '(film)' removed. The content is the synopsis of the media based on 1 - 4 of the first paragraphs on the media's Wikipedia page. It removes things like links to sources and Asian pronunciations (quite basic right now).
+### `synopsis(mediaTitle, [mediaTypes])`
 
-Contributing
-------------
+`mediaTitle` is a string.
 
-Only real-world use can help improve the code that cleans up the content removing the irrelevant and making sure the title doesn't have anything extra included. If you spot unexpected output then please create an issue or submit a pull request and I'll try to fix.
+`mediaTypes` is an optional array of strings. Only the first non-empty type is added to the Wikipedia search. All of them are used when choosing paragraphs.
 
-Tests?
-------
+The returned Promise resolves to an object with:
+
+- `title` — the cleaned Wikipedia title
+- `content` — the synopsis, including a `Source: [Wikipedia](...)` line
+
+The Promise rejects with an `Error` when Wikipedia has no matching page or the request fails.
+
+## Contributing
+
+The cleanup rules are deliberately small. If a real title comes back with a pronunciation, citation, or disambiguator still attached, open an issue with the query, the Wikipedia URL, and what the title or synopsis should have been.
+
+```bash
+npm test
+npm run lint
+```
 
-Eheheheh yeah, this library is like one big side effect. Tests this early for stuff like the content and title clean ups would have to be updated with every change and ultimately not really help all that much. I'm usually super pro-testing so if the library ever goes >150 lines I'll start breaking out functions and writing tests for the pure parts. Right now though linking to source wikipedia page and to the output and explaining what should be different in an issue is good enough.
+Vitest covers title cleanup, paragraph selection, pronunciation stripping, and the Wikipedia client with a stand-in for `fetch`. The tests do not call Wikipedia.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { type Synopsis } from './text.js';
+export type { Synopsis };
+/**
+ * Look up a short synopsis for a movie, book, anime, game, or other media.
+ * Only the first non-empty media type is added to the Wikipedia search.
+ * Every non-empty type is used when choosing lead paragraphs.
+ */
+export declare function synopsis(mediaTitle: string, mediaTypes?: readonly string[]): Promise<Synopsis>;

package/dist/index.js

@@ -0,0 +1,15 @@
+import { buildSynopsis } from './text.js';
+import { fetchWikipediaLead } from './wikipedia.js';
+function mediaTypeList(mediaTypes) {
+    return [...mediaTypes];
+}
+/**
+ * Look up a short synopsis for a movie, book, anime, game, or other media.
+ * Only the first non-empty media type is added to the Wikipedia search.
+ * Every non-empty type is used when choosing lead paragraphs.
+ */
+export async function synopsis(mediaTitle, mediaTypes = []) {
+    const types = mediaTypeList(mediaTypes);
+    const page = await fetchWikipediaLead(mediaTitle.trim(), types);
+    return buildSynopsis(page, types);
+}

package/dist/text.d.ts

@@ -0,0 +1,13 @@
+export interface Synopsis {
+    content: string;
+    title: string;
+}
+export interface LeadPage {
+    extract: string;
+    title: string;
+    url: string;
+}
+export declare function getMediaTitle(fullLinkText: string): string;
+export declare function getContentText(text: string, mediaTypes: readonly string[]): string;
+export declare function removeUnwantedChars(text: string, title: string): string;
+export declare function buildSynopsis(page: LeadPage, mediaTypes: readonly string[]): Synopsis;

package/dist/text.js

@@ -0,0 +1,71 @@
+// Trailing disambiguator, such as " (film)" or " (manga)".
+const TRAILING_DISAMBIGUATION = /\s+\([^)]*\)$/;
+function escapeRegExp(value) {
+    // Characters that would otherwise change the meaning of a regular expression.
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function getMediaTitle(fullLinkText) {
+    const withoutSite = fullLinkText.split('- Wikipedia')[0].trim();
+    // "List of Naruto episodes" keeps "Naruto".
+    const seriesName = /List of (.*) episodes/i.exec(withoutSite)?.[1]?.trim();
+    if (seriesName) {
+        return seriesName;
+    }
+    return withoutSite.replace(TRAILING_DISAMBIGUATION, '').trim();
+}
+export function getContentText(text, mediaTypes) {
+    const paragraphs = text
+        // One or more newlines separate paragraphs.
+        .split(/\n+/)
+        .map((paragraph) => paragraph.trim())
+        .filter(Boolean);
+    const opening = paragraphs[0];
+    if (opening === undefined) {
+        return '';
+    }
+    const needles = mediaTypes
+        .map((type) => type.trim())
+        .filter(Boolean);
+    if (needles.length === 0) {
+        return opening;
+    }
+    const pattern = needles.map(escapeRegExp).join('|');
+    // Case-insensitive whole word or phrase for any supplied media type.
+    const mediaTypePattern = new RegExp(`\\b(?:${pattern})\\b`, 'i');
+    const limit = Math.min(4, paragraphs.length);
+    for (let index = 0; index < limit; index += 1) {
+        const paragraph = paragraphs[index];
+        if (paragraph !== undefined && mediaTypePattern.test(paragraph)) {
+            return paragraphs.slice(0, index + 1).join('\n\n');
+        }
+    }
+    return opening;
+}
+export function removeUnwantedChars(text, title) {
+    // Parenthetical immediately after the title. `.` stops at a newline.
+    const titlePronunciation = new RegExp(`${escapeRegExp(title)}\\s*\\(.+?\\)`, 'i');
+    // Japanese or Hepburn pronunciation, including when it follows the original name. Stays on one line.
+    const namedPronunciation = /\s*\([^)\n]*(?:Japanese:|Hepburn:|[\u3040-\u30ff\u3400-\u9fff])[^)\n]*\)/g;
+    return text
+        .replace(namedPronunciation, '')
+        .replace(titlePronunciation, title)
+        // Citation markers such as [1].
+        .replace(/\[.*?\]/g, '')
+        // Runs of spaces or tabs left by the removals above.
+        .replace(/[ \t]{2,}/g, ' ')
+        // A space before punctuation, such as " ," or " .".
+        .replace(/[ \t]+([,.;:])/g, '$1')
+        .trim();
+}
+export function buildSynopsis(page, mediaTypes) {
+    const title = getMediaTitle(page.title);
+    const relevantParagraphs = getContentText(page.extract, mediaTypes);
+    const content = removeUnwantedChars(relevantParagraphs, title);
+    if (!content) {
+        throw new Error('No synopsis text found on the Wikipedia page');
+    }
+    return {
+        content: `${content}\n\nSource: [Wikipedia](${page.url})`,
+        title
+    };
+}

package/dist/wikipedia.d.ts

@@ -0,0 +1,3 @@
+import type { LeadPage } from './text.js';
+export declare function searchQuery(mediaTitle: string, mediaTypes: readonly string[]): string;
+export declare function fetchWikipediaLead(mediaTitle: string, mediaTypes: readonly string[]): Promise<LeadPage>;

package/dist/wikipedia.js

@@ -0,0 +1,74 @@
+import pkg from '../package.json' with { type: 'json' };
+const API_URL = 'https://en.wikipedia.org/w/api.php';
+const USER_AGENT = `media-synopsis/${pkg.version} (https://github.com/thethomaseffect/node-media-synopsis; thethomaseffect@gmail.com)`;
+export function searchQuery(mediaTitle, mediaTypes) {
+    const hint = mediaTypes
+        .map((type) => type.trim())
+        .find((type) => type !== '');
+    if (!hint) {
+        return mediaTitle;
+    }
+    return `${mediaTitle} ${hint}`;
+}
+function pageUrl(page) {
+    if (typeof page.fullurl === 'string' && page.fullurl) {
+        return page.fullurl;
+    }
+    const slug = encodeURIComponent((page.title ?? '').replace(/ /g, '_'));
+    return `https://en.wikipedia.org/wiki/${slug}`;
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+function isWikiBody(value) {
+    return typeof value === 'object' && value !== null;
+}
+function failureMessage(response, body) {
+    if (isWikiBody(body) && typeof body.error?.info === 'string') {
+        return body.error.info;
+    }
+    return `Wikipedia request failed with status ${response.status}`;
+}
+export async function fetchWikipediaLead(mediaTitle, mediaTypes) {
+    const params = new URLSearchParams({
+        action: 'query',
+        explaintext: '1',
+        exintro: '1',
+        format: 'json',
+        formatversion: '2',
+        generator: 'search',
+        gsrlimit: '1',
+        gsrsearch: searchQuery(mediaTitle, mediaTypes),
+        inprop: 'url',
+        prop: 'extracts|info',
+        redirects: '1'
+    });
+    const response = await fetch(`${API_URL}?${params.toString()}`, {
+        headers: {
+            Accept: 'application/json',
+            'User-Agent': USER_AGENT
+        },
+        signal: AbortSignal.timeout(15000)
+    });
+    const body = await readJson(response);
+    if (!response.ok || (isWikiBody(body) && body.error)) {
+        throw new Error(failureMessage(response, body));
+    }
+    if (!isWikiBody(body)) {
+        throw new Error('Wikipedia returned a response that was not JSON');
+    }
+    const page = body.query?.pages?.[0];
+    if (!page || page.missing === true || typeof page.title !== 'string' || typeof page.extract !== 'string' || page.extract.trim() === '') {
+        throw new Error('No Wikipedia results found for that media title and media type');
+    }
+    return {
+        extract: page.extract,
+        title: page.title,
+        url: pageUrl(page)
+    };
+}

package/package.json

@@ -1,25 +1,36 @@
 {
   "name": "media-synopsis",
-  "version": "0.1.1",
-  "description": "Get a synopsis for a Movie, Anime, Book or some other media using Google and Wikipedia.",
-  "main": "index.js",
-  "dependencies": {
-    "google": "~0.3.3",
-    "request": "~2.37.0",
-    "unfluff": "~0.5.0"
+  "version": "1.0.0",
+  "description": "Get a synopsis for a movie, anime, book, or other media from Wikipedia.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsc --noEmit && npm run build && vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run lint && npm test"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/thethomaseffect/node-media-synopsis"
+    "url": "git+https://github.com/thethomaseffect/node-media-synopsis.git"
   },
   "bugs": {
     "url": "https://github.com/thethomaseffect/node-media-synopsis/issues"
   },
-  "readmeFilename": "README.md",
-  "devDependencies": {},
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "keywords": [
     "anime",
     "movie",
@@ -33,5 +44,17 @@
     "name": "Thomas Geraghty",
     "email": "thethomaseffect@gmail.com"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.12.0",
+    "jiti": "^2.7.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.4"
+  }
 }

package/.npmignore

@@ -1,25 +0,0 @@
-# Logs
-logs
-*.log
-
-# Runtime data
-pids
-*.pid
-*.seed
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-
-# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Compiled binary addons (http://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directory
-# Deployed apps should consider commenting this line out:
-# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
-node_modules

package/index.js

@@ -1,84 +0,0 @@
-var extractor = require('unfluff');
-var request = require('request');
-var google = require('google');
-
-exports.synopsis = function(mediaTitle, mediaType, callback) {
-    if (mediaType === null || mediaType === undefined) {
-        mediaType = [''];
-    }
-    // Allow providing a string for mediaType but convert it to array
-    // to simplify code
-    if (typeof mediaType === 'string'){
-        mediaType = [mediaType];
-    }
-    // Only use first media type to keep things simple
-    google(mediaTitle + ' ' + mediaType[0] + ' site:wikipedia.org',
-        function(err, next, links){
-            if (err) {
-                callback(err);
-                return;
-            }
-            if (!links[0]) {
-                callback("No Wikipedia Results found for that mediaTitle and mediaType");
-                return;
-            }
-            // Sometimes this will be 'List of x Episodes' for TV shows. Example: 're hamatora'
-            var title = getMediaTitle(links[0].title.trim());
-            request(links[0].link, function (error, response, body) {
-            if (!error && response.statusCode == 200) {
-                data = extractor(body);
-                getContentText(data.text, mediaType);
-                var releventParagraphs = getContentText(data.text, mediaType);
-                callback(undefined,
-                {
-                    title: title,
-                    content: removeUnwantedChars(releventParagraphs, title) +
-                        '\n\nSource: [Wikipedia](' + links[0].link + ')'
-                });
-        } else {
-            callback(error);
-        }
-    });
-    });
-};
-
-
-function getMediaTitle(fullLinkText) {
-    var title = fullLinkText.split('- Wikipedia')[0];
-    var listOfEpsRegex = /.*List of (.*) episodes/.exec(title);
-    if(listOfEpsRegex) {
-        return listOfEpsRegex[1];
-    }
-    var filmRegex = /(.*) \(film\)/.exec(title);
-    if(filmRegex) {
-        return filmRegex[1];
-    }
-    return title;
-}
-
-getContentText = function(text, mediaTypes) {
-    paragraphs = text.split('\n');
-    // This will build an OR type regex for each media type
-    var re = new RegExp('\\b' + mediaTypes.join('\\b|\\b') + '\\b', 'i');
-    // Media type(s) is in first paragraph, return it
-    if(re.test(paragraphs[0])) {
-        return paragraphs[0];
-    }
-    // Media type(s) in in first 4 parapraphs, return all
-    // paragraphs until it's mention
-    for(var i = 1; i < 4; i++) {
-        if(re.test(paragraphs[i])) {
-            return paragraphs.slice(0, i + 1).join('\n');
-        }
-    }
-    // Media type not found, return first paragraph
-    return paragraphs[0];
-};
-
-function removeUnwantedChars(text, title) {
-    // TODO: Replace [\s\S] with . once issue with unfluff is resolved
-    var AsianPronunciationsRegex = new RegExp(title + '\\([\\s\\S]*?\\) ', 'i');
-    return text
-        .replace(AsianPronunciationsRegex, title) // Removes Asian pronunciations
-        .replace(/(\[.*?\])/ig, ''); // Removes links to sources
-}