parse-torrent-path 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Aldarondo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# parse-torrent-path
+
+Modular, handler-based media metadata parser for filenames and paths. Optimized for general media library organization and complex naming conventions.
+
+## Features
+
+- **Modular Handler System**: Extensible architecture using regex and functional handlers.
+- **Extended Pattern Support**: Specialized patterns (e.g., `S1 - E01`, `- N -`).
+- **Path Context**: Automatically extracts season info from parent folder names (e.g., `Season 01/`).
+- **Extras Detection**: Identifies bonus content, deleted scenes, and featurettes.
+- **Episode Title Extraction**: Captures episode titles embedded in filenames.
+- **Movie Year Fallbacks**: Advanced detection for embedded broadcast years.
+
+## Installation
+
+```bash
+npm install parse-torrent-path
+```
+
+## Usage
+
+### Simple Parsing
+
+```typescript
+import { parsePath } from 'parse-torrent-path';
+
+const info = parsePath('Show.Name.S01E02.1080p.mkv');
+// {
+//   title: 'Show Name',
+//   season: 1,
+//   episode: 2,
+//   resolution: '1080p'
+// }
+```
+
+### Path Context Awareness
+
+```typescript
+// Uses folder name to infer missing season
+const info = parsePath('Season 05/Episode 01.mkv');
+// {
+//   title: 'Episode 01',
+//   season: 5,
+//   episode: 1
+// }
+```
+
+### Alternate Patterns
+
+```typescript
+const info = parsePath('Show.Name.S1 - E01 - Pilot.mp4');
+// {
+//   title: 'Show Name',
+//   season: 1,
+//   episode: 1,
+//   episodeTitle: 'Pilot'
+// }
+```
+
+## Advanced Usage
+
+You can leverage the exported `getDefaultParser()` which comes pre-loaded with all standard `parse-torrent-title` rules and our extended path-aware handlers, or you can create a fresh `Parser` and add your own custom logic:
+
+```typescript
+import { getDefaultParser } from 'parse-torrent-path';
+
+const parser = getDefaultParser();
+
+// Add custom logic
+parser.addHandler('customTag', /\[(TAG)\]/i, { type: 'lowercase' });
+
+const info = parser.parse('Show [TAG] S01E01.mkv');
+```
+
+## Acknowledgements
+
+This package is heavily inspired by and built upon the excellent [parse-torrent-title](https://github.com/clement-escolano/parse-torrent-title) package by clement-escolano. It adapts its core "Handlers" architecture while adding context-aware path parsing and extended matching rules.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,109 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Parser: () => Parser2,
+  getDefaultParser: () => getDefaultParser,
+  parsePath: () => parsePath
+});
+module.exports = __toCommonJS(index_exports);
+var import_path = __toESM(require("path"), 1);
+var ptt = __toESM(require("parse-torrent-title"), 1);
+
+// src/defaults.ts
+function addExtendedHandlers(parser) {
+  parser.addHandler("year", /^(.*\D)(\d{4})(?=\s|[-_]|$)/, { type: "integer", skipIfAlreadyFound: true });
+  parser.addHandler("season", /S([0-9]{1,2})\s*-\s*E[0-9]{1,2}/i, { type: "integer" });
+  parser.addHandler("episode", /S[0-9]{1,2}\s*-\s*E([0-9]{1,5})/i, { type: "integer" });
+  parser.addHandler("episode", /(?:^|\s)-\s*(\d{1,3})\s*-\s+/i, { type: "integer" });
+  parser.addHandler("season", /(\d{1,2})x(\d{2,3})/i, { type: "integer" });
+  parser.addHandler("episode", /\d{1,2}x(\d{2,3})/i, { type: "integer" });
+  parser.addHandler("season", /Season\s+(\d+)\s+Episode\s+\d+/i, { type: "integer" });
+  parser.addHandler("episode", /Season\s+\d+\s+Episode\s+(\d+)/i, { type: "integer" });
+  parser.addHandler("episode", /(?:^|[.\s-_])(?:Episode|Ep)[.\s-_]?(\d{1,3})(?:[.\s-_]|$)/i, { type: "integer", skipIfAlreadyFound: true });
+  const EXTRAS_PATTERN = /\b(?:extras?|bts|featurettes?|behind[\s_-]the[\s_-]scenes?|deleted[\s_-]scenes?|interviews?|trailers?|bloopers?|outtakes?|shorts?|making[\s_-]of|bonus)\b/i;
+  parser.addHandler("isExtras", ({ title, result }) => {
+    if (title && result && EXTRAS_PATTERN.test(title)) {
+      result.isExtras = true;
+    }
+  });
+  parser.addHandler("episodeTitle", ({ title, result }) => {
+    if (title && result && result.episode !== void 0) {
+      const patterns = [
+        /[Ss]\d{1,2}[Ee]\d{1,3}[\s._-]+(.*)/,
+        /[Ss]\d{1,2}\s*-\s*[Ee]\d{1,3}[\s._-]+(.*)/,
+        /(?:^|\s)-\s*\d{1,3}\s*-\s+(.*)/,
+        /\d{1,2}x\d{2,3}[\s._-]+(.*)/,
+        /Season\s+\d+\s+Episode\s+\d+[\s._-]+(.*)/
+      ];
+      for (const p of patterns) {
+        const match = title.match(p);
+        if (match && match[1]) {
+          const cleaned = match[1].replace(/\.(mkv|mp4|avi|mov|wmv|m4v|ts|m2ts|webm)$/i, "").trim();
+          result.episodeTitle = cleaned;
+          break;
+        }
+      }
+    }
+  });
+}
+
+// src/index.ts
+var Parser2 = ptt.Parser;
+var defaultParser = null;
+function getDefaultParser() {
+  if (!defaultParser) {
+    defaultParser = new ptt.Parser();
+    ptt.addDefaults(defaultParser);
+    addExtendedHandlers(defaultParser);
+  }
+  return defaultParser;
+}
+function parsePath(filePath, options = {}) {
+  const parser = options.includeDefaults !== false ? getDefaultParser() : new ptt.Parser();
+  const basename = import_path.default.basename(filePath);
+  const folderName = import_path.default.dirname(filePath) !== "." ? import_path.default.basename(import_path.default.dirname(filePath)) : "";
+  const result = parser.parse(basename);
+  if (result.season === void 0 && folderName) {
+    const seasonMatch = folderName.match(/^(?:Season\s+|S)([0-9]{1,2})$/i);
+    if (seasonMatch) {
+      result.season = parseInt(seasonMatch[1], 10);
+    }
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Parser,
+  getDefaultParser,
+  parsePath
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/defaults.ts"],"sourcesContent":["import path from 'path';\r\nimport * as ptt from 'parse-torrent-title';\r\nimport { addExtendedHandlers } from './defaults.js';\r\nimport { ParsedInfo, ParserOptions } from './types.js';\r\n\r\nexport const Parser = ptt.Parser;\r\nexport * from './types.js';\r\n\r\nlet defaultParser: ptt.Parser<ParsedInfo> | null = null;\r\n\r\n/**\r\n * Get the default parser with standard and extended handlers.\r\n */\r\nexport function getDefaultParser(): ptt.Parser<ParsedInfo> {\r\n    if (!defaultParser) {\r\n        defaultParser = new ptt.Parser<ParsedInfo>();\r\n        ptt.addDefaults(defaultParser);\r\n        addExtendedHandlers(defaultParser);\r\n    }\r\n    return defaultParser;\r\n}\r\n\r\n/**\r\n * High-level function to parse a filename or path into metadata.\r\n * @param filePath The filename or full path to parse.\r\n * @param options Options for the parser.\r\n */\r\nexport function parsePath(filePath: string, options: ParserOptions = {}): ParsedInfo {\r\n    const parser = options.includeDefaults !== false ? getDefaultParser() : new ptt.Parser<ParsedInfo>();\r\n\r\n    const basename = path.basename(filePath);\r\n    const folderName = path.dirname(filePath) !== '.' ? path.basename(path.dirname(filePath)) : '';\r\n\r\n    // Parse the basename first\r\n    const result = parser.parse(basename) as ParsedInfo;\r\n\r\n    // If it's a \"Season\" folder or we need more context from the path, we can add it here.\r\n    // For example, if season is missing but folder is \"Season 01\"\r\n    if (result.season === undefined && folderName) {\r\n        const seasonMatch = folderName.match(/^(?:Season\\s+|S)([0-9]{1,2})$/i);\r\n        if (seasonMatch) {\r\n            result.season = parseInt(seasonMatch[1], 10);\r\n        }\r\n    }\r\n\r\n    return result;\r\n}\r\n\r\n","import { Parser as PTTParser } from 'parse-torrent-title';\r\nimport { ParsedInfo, HandlerContext } from './types.js';\r\n\r\nexport function addExtendedHandlers(parser: PTTParser<ParsedInfo>): void {\r\n    // Embedded year fallback: \"ShowName2006\"\r\n    parser.addHandler('year', /^(.*\\D)(\\d{4})(?=\\s|[-_]|$)/, { type: 'integer', skipIfAlreadyFound: true });\r\n\r\n    // Alternate Style: S1 - E01\r\n    parser.addHandler('season', /S([0-9]{1,2})\\s*-\\s*E[0-9]{1,2}/i, { type: 'integer' });\r\n    parser.addHandler('episode', /S[0-9]{1,2}\\s*-\\s*E([0-9]{1,5})/i, { type: 'integer' });\r\n\r\n    // Alternate Style: - N - (standalone episode)\r\n    parser.addHandler('episode', /(?:^|\\s)-\\s*(\\d{1,3})\\s*-\\s+/i, { type: 'integer' });\r\n\r\n    // NxNN pattern (e.g. 1x01)\r\n    parser.addHandler('season', /(\\d{1,2})x(\\d{2,3})/i, { type: 'integer' });\r\n    parser.addHandler('episode', /\\d{1,2}x(\\d{2,3})/i, { type: 'integer' });\r\n\r\n    // Spelled out: Season N Episode N\r\n    parser.addHandler('season', /Season\\s+(\\d+)\\s+Episode\\s+\\d+/i, { type: 'integer' });\r\n    parser.addHandler('episode', /Season\\s+\\d+\\s+Episode\\s+(\\d+)/i, { type: 'integer' });\r\n\r\n    // Standalone Episode N (fallback)\r\n    parser.addHandler('episode', /(?:^|[.\\s-_])(?:Episode|Ep)[.\\s-_]?(\\d{1,3})(?:[.\\s-_]|$)/i, { type: 'integer', skipIfAlreadyFound: true });\r\n\r\n    // --- Extras Detection ---\r\n    const EXTRAS_PATTERN = /\\b(?:extras?|bts|featurettes?|behind[\\s_-]the[\\s_-]scenes?|deleted[\\s_-]scenes?|interviews?|trailers?|bloopers?|outtakes?|shorts?|making[\\s_-]of|bonus)\\b/i;\r\n    parser.addHandler('isExtras', ({ title, result }: HandlerContext) => {\r\n        if (title && result && EXTRAS_PATTERN.test(title)) {\r\n            result.isExtras = true;\r\n        }\r\n    });\r\n\r\n    // --- Episode Title Cleanup ---\r\n    // If we have an episode, try to find the remainder as the episode title\r\n    parser.addHandler('episodeTitle', ({ title, result }: HandlerContext) => {\r\n        if (title && result && result.episode !== undefined) {\r\n            // Look for common separators after the episode number\r\n            const patterns = [\r\n                /[Ss]\\d{1,2}[Ee]\\d{1,3}[\\s._-]+(.*)/,\r\n                /[Ss]\\d{1,2}\\s*-\\s*[Ee]\\d{1,3}[\\s._-]+(.*)/,\r\n                /(?:^|\\s)-\\s*\\d{1,3}\\s*-\\s+(.*)/,\r\n                /\\d{1,2}x\\d{2,3}[\\s._-]+(.*)/,\r\n                /Season\\s+\\d+\\s+Episode\\s+\\d+[\\s._-]+(.*)/\r\n            ];\r\n\r\n            for (const p of patterns) {\r\n                const match = title.match(p);\r\n                if (match && match[1]) {\r\n                    const cleaned = match[1]\r\n                        .replace(/\\.(mkv|mp4|avi|mov|wmv|m4v|ts|m2ts|webm)$/i, '')\r\n                        .trim();\r\n                    result.episodeTitle = cleaned;\r\n                    break;\r\n                }\r\n            }\r\n        }\r\n    });\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,gBAAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,kBAAiB;AACjB,UAAqB;;;ACEd,SAAS,oBAAoB,QAAqC;AAErE,SAAO,WAAW,QAAQ,+BAA+B,EAAE,MAAM,WAAW,oBAAoB,KAAK,CAAC;AAGtG,SAAO,WAAW,UAAU,oCAAoC,EAAE,MAAM,UAAU,CAAC;AACnF,SAAO,WAAW,WAAW,oCAAoC,EAAE,MAAM,UAAU,CAAC;AAGpF,SAAO,WAAW,WAAW,iCAAiC,EAAE,MAAM,UAAU,CAAC;AAGjF,SAAO,WAAW,UAAU,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACvE,SAAO,WAAW,WAAW,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGtE,SAAO,WAAW,UAAU,mCAAmC,EAAE,MAAM,UAAU,CAAC;AAClF,SAAO,WAAW,WAAW,mCAAmC,EAAE,MAAM,UAAU,CAAC;AAGnF,SAAO,WAAW,WAAW,8DAA8D,EAAE,MAAM,WAAW,oBAAoB,KAAK,CAAC;AAGxI,QAAM,iBAAiB;AACvB,SAAO,WAAW,YAAY,CAAC,EAAE,OAAO,OAAO,MAAsB;AACjE,QAAI,SAAS,UAAU,eAAe,KAAK,KAAK,GAAG;AAC/C,aAAO,WAAW;AAAA,IACtB;AAAA,EACJ,CAAC;AAID,SAAO,WAAW,gBAAgB,CAAC,EAAE,OAAO,OAAO,MAAsB;AACrE,QAAI,SAAS,UAAU,OAAO,YAAY,QAAW;AAEjD,YAAM,WAAW;AAAA,QACb;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACJ;AAEA,iBAAW,KAAK,UAAU;AACtB,cAAM,QAAQ,MAAM,MAAM,CAAC;AAC3B,YAAI,SAAS,MAAM,CAAC,GAAG;AACnB,gBAAM,UAAU,MAAM,CAAC,EAClB,QAAQ,8CAA8C,EAAE,EACxD,KAAK;AACV,iBAAO,eAAe;AACtB;AAAA,QACJ;AAAA,MACJ;AAAA,IACJ;AAAA,EACJ,CAAC;AACL;;;ADrDO,IAAMC,UAAa;AAG1B,IAAI,gBAA+C;AAK5C,SAAS,mBAA2C;AACvD,MAAI,CAAC,eAAe;AAChB,oBAAgB,IAAQ,WAAmB;AAC3C,IAAI,gBAAY,aAAa;AAC7B,wBAAoB,aAAa;AAAA,EACrC;AACA,SAAO;AACX;AAOO,SAAS,UAAU,UAAkB,UAAyB,CAAC,GAAe;AACjF,QAAM,SAAS,QAAQ,oBAAoB,QAAQ,iBAAiB,IAAI,IAAQ,WAAmB;AAEnG,QAAM,WAAW,YAAAC,QAAK,SAAS,QAAQ;AACvC,QAAM,aAAa,YAAAA,QAAK,QAAQ,QAAQ,MAAM,MAAM,YAAAA,QAAK,SAAS,YAAAA,QAAK,QAAQ,QAAQ,CAAC,IAAI;AAG5F,QAAM,SAAS,OAAO,MAAM,QAAQ;AAIpC,MAAI,OAAO,WAAW,UAAa,YAAY;AAC3C,UAAM,cAAc,WAAW,MAAM,gCAAgC;AACrE,QAAI,aAAa;AACb,aAAO,SAAS,SAAS,YAAY,CAAC,GAAG,EAAE;AAAA,IAC/C;AAAA,EACJ;AAEA,SAAO;AACX;","names":["Parser","Parser","path"]}

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+import * as ptt from 'parse-torrent-title';
+import { DefaultParserResult } from 'parse-torrent-title';
+
+interface ParsedInfo extends DefaultParserResult {
+    episodeTitle?: string;
+    showTitle?: string;
+    isExtras?: boolean;
+    [key: string]: any;
+}
+interface HandlerContext {
+    title?: string;
+    result?: ParsedInfo;
+}
+type HandlerFunction = (context: HandlerContext) => void;
+interface ParserOptions {
+    includeDefaults?: boolean;
+}
+
+declare const Parser: typeof ptt.Parser;
+
+/**
+ * Get the default parser with standard and extended handlers.
+ */
+declare function getDefaultParser(): ptt.Parser<ParsedInfo>;
+/**
+ * High-level function to parse a filename or path into metadata.
+ * @param filePath The filename or full path to parse.
+ * @param options Options for the parser.
+ */
+declare function parsePath(filePath: string, options?: ParserOptions): ParsedInfo;
+
+export { type HandlerContext, type HandlerFunction, type ParsedInfo, Parser, type ParserOptions, getDefaultParser, parsePath };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import * as ptt from 'parse-torrent-title';
+import { DefaultParserResult } from 'parse-torrent-title';
+
+interface ParsedInfo extends DefaultParserResult {
+    episodeTitle?: string;
+    showTitle?: string;
+    isExtras?: boolean;
+    [key: string]: any;
+}
+interface HandlerContext {
+    title?: string;
+    result?: ParsedInfo;
+}
+type HandlerFunction = (context: HandlerContext) => void;
+interface ParserOptions {
+    includeDefaults?: boolean;
+}
+
+declare const Parser: typeof ptt.Parser;
+
+/**
+ * Get the default parser with standard and extended handlers.
+ */
+declare function getDefaultParser(): ptt.Parser<ParsedInfo>;
+/**
+ * High-level function to parse a filename or path into metadata.
+ * @param filePath The filename or full path to parse.
+ * @param options Options for the parser.
+ */
+declare function parsePath(filePath: string, options?: ParserOptions): ParsedInfo;
+
+export { type HandlerContext, type HandlerFunction, type ParsedInfo, Parser, type ParserOptions, getDefaultParser, parsePath };

package/dist/index.js

@@ -0,0 +1,72 @@
+// src/index.ts
+import path from "path";
+import * as ptt from "parse-torrent-title";
+
+// src/defaults.ts
+function addExtendedHandlers(parser) {
+  parser.addHandler("year", /^(.*\D)(\d{4})(?=\s|[-_]|$)/, { type: "integer", skipIfAlreadyFound: true });
+  parser.addHandler("season", /S([0-9]{1,2})\s*-\s*E[0-9]{1,2}/i, { type: "integer" });
+  parser.addHandler("episode", /S[0-9]{1,2}\s*-\s*E([0-9]{1,5})/i, { type: "integer" });
+  parser.addHandler("episode", /(?:^|\s)-\s*(\d{1,3})\s*-\s+/i, { type: "integer" });
+  parser.addHandler("season", /(\d{1,2})x(\d{2,3})/i, { type: "integer" });
+  parser.addHandler("episode", /\d{1,2}x(\d{2,3})/i, { type: "integer" });
+  parser.addHandler("season", /Season\s+(\d+)\s+Episode\s+\d+/i, { type: "integer" });
+  parser.addHandler("episode", /Season\s+\d+\s+Episode\s+(\d+)/i, { type: "integer" });
+  parser.addHandler("episode", /(?:^|[.\s-_])(?:Episode|Ep)[.\s-_]?(\d{1,3})(?:[.\s-_]|$)/i, { type: "integer", skipIfAlreadyFound: true });
+  const EXTRAS_PATTERN = /\b(?:extras?|bts|featurettes?|behind[\s_-]the[\s_-]scenes?|deleted[\s_-]scenes?|interviews?|trailers?|bloopers?|outtakes?|shorts?|making[\s_-]of|bonus)\b/i;
+  parser.addHandler("isExtras", ({ title, result }) => {
+    if (title && result && EXTRAS_PATTERN.test(title)) {
+      result.isExtras = true;
+    }
+  });
+  parser.addHandler("episodeTitle", ({ title, result }) => {
+    if (title && result && result.episode !== void 0) {
+      const patterns = [
+        /[Ss]\d{1,2}[Ee]\d{1,3}[\s._-]+(.*)/,
+        /[Ss]\d{1,2}\s*-\s*[Ee]\d{1,3}[\s._-]+(.*)/,
+        /(?:^|\s)-\s*\d{1,3}\s*-\s+(.*)/,
+        /\d{1,2}x\d{2,3}[\s._-]+(.*)/,
+        /Season\s+\d+\s+Episode\s+\d+[\s._-]+(.*)/
+      ];
+      for (const p of patterns) {
+        const match = title.match(p);
+        if (match && match[1]) {
+          const cleaned = match[1].replace(/\.(mkv|mp4|avi|mov|wmv|m4v|ts|m2ts|webm)$/i, "").trim();
+          result.episodeTitle = cleaned;
+          break;
+        }
+      }
+    }
+  });
+}
+
+// src/index.ts
+var Parser2 = ptt.Parser;
+var defaultParser = null;
+function getDefaultParser() {
+  if (!defaultParser) {
+    defaultParser = new ptt.Parser();
+    ptt.addDefaults(defaultParser);
+    addExtendedHandlers(defaultParser);
+  }
+  return defaultParser;
+}
+function parsePath(filePath, options = {}) {
+  const parser = options.includeDefaults !== false ? getDefaultParser() : new ptt.Parser();
+  const basename = path.basename(filePath);
+  const folderName = path.dirname(filePath) !== "." ? path.basename(path.dirname(filePath)) : "";
+  const result = parser.parse(basename);
+  if (result.season === void 0 && folderName) {
+    const seasonMatch = folderName.match(/^(?:Season\s+|S)([0-9]{1,2})$/i);
+    if (seasonMatch) {
+      result.season = parseInt(seasonMatch[1], 10);
+    }
+  }
+  return result;
+}
+export {
+  Parser2 as Parser,
+  getDefaultParser,
+  parsePath
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/defaults.ts"],"sourcesContent":["import path from 'path';\r\nimport * as ptt from 'parse-torrent-title';\r\nimport { addExtendedHandlers } from './defaults.js';\r\nimport { ParsedInfo, ParserOptions } from './types.js';\r\n\r\nexport const Parser = ptt.Parser;\r\nexport * from './types.js';\r\n\r\nlet defaultParser: ptt.Parser<ParsedInfo> | null = null;\r\n\r\n/**\r\n * Get the default parser with standard and extended handlers.\r\n */\r\nexport function getDefaultParser(): ptt.Parser<ParsedInfo> {\r\n    if (!defaultParser) {\r\n        defaultParser = new ptt.Parser<ParsedInfo>();\r\n        ptt.addDefaults(defaultParser);\r\n        addExtendedHandlers(defaultParser);\r\n    }\r\n    return defaultParser;\r\n}\r\n\r\n/**\r\n * High-level function to parse a filename or path into metadata.\r\n * @param filePath The filename or full path to parse.\r\n * @param options Options for the parser.\r\n */\r\nexport function parsePath(filePath: string, options: ParserOptions = {}): ParsedInfo {\r\n    const parser = options.includeDefaults !== false ? getDefaultParser() : new ptt.Parser<ParsedInfo>();\r\n\r\n    const basename = path.basename(filePath);\r\n    const folderName = path.dirname(filePath) !== '.' ? path.basename(path.dirname(filePath)) : '';\r\n\r\n    // Parse the basename first\r\n    const result = parser.parse(basename) as ParsedInfo;\r\n\r\n    // If it's a \"Season\" folder or we need more context from the path, we can add it here.\r\n    // For example, if season is missing but folder is \"Season 01\"\r\n    if (result.season === undefined && folderName) {\r\n        const seasonMatch = folderName.match(/^(?:Season\\s+|S)([0-9]{1,2})$/i);\r\n        if (seasonMatch) {\r\n            result.season = parseInt(seasonMatch[1], 10);\r\n        }\r\n    }\r\n\r\n    return result;\r\n}\r\n\r\n","import { Parser as PTTParser } from 'parse-torrent-title';\r\nimport { ParsedInfo, HandlerContext } from './types.js';\r\n\r\nexport function addExtendedHandlers(parser: PTTParser<ParsedInfo>): void {\r\n    // Embedded year fallback: \"ShowName2006\"\r\n    parser.addHandler('year', /^(.*\\D)(\\d{4})(?=\\s|[-_]|$)/, { type: 'integer', skipIfAlreadyFound: true });\r\n\r\n    // Alternate Style: S1 - E01\r\n    parser.addHandler('season', /S([0-9]{1,2})\\s*-\\s*E[0-9]{1,2}/i, { type: 'integer' });\r\n    parser.addHandler('episode', /S[0-9]{1,2}\\s*-\\s*E([0-9]{1,5})/i, { type: 'integer' });\r\n\r\n    // Alternate Style: - N - (standalone episode)\r\n    parser.addHandler('episode', /(?:^|\\s)-\\s*(\\d{1,3})\\s*-\\s+/i, { type: 'integer' });\r\n\r\n    // NxNN pattern (e.g. 1x01)\r\n    parser.addHandler('season', /(\\d{1,2})x(\\d{2,3})/i, { type: 'integer' });\r\n    parser.addHandler('episode', /\\d{1,2}x(\\d{2,3})/i, { type: 'integer' });\r\n\r\n    // Spelled out: Season N Episode N\r\n    parser.addHandler('season', /Season\\s+(\\d+)\\s+Episode\\s+\\d+/i, { type: 'integer' });\r\n    parser.addHandler('episode', /Season\\s+\\d+\\s+Episode\\s+(\\d+)/i, { type: 'integer' });\r\n\r\n    // Standalone Episode N (fallback)\r\n    parser.addHandler('episode', /(?:^|[.\\s-_])(?:Episode|Ep)[.\\s-_]?(\\d{1,3})(?:[.\\s-_]|$)/i, { type: 'integer', skipIfAlreadyFound: true });\r\n\r\n    // --- Extras Detection ---\r\n    const EXTRAS_PATTERN = /\\b(?:extras?|bts|featurettes?|behind[\\s_-]the[\\s_-]scenes?|deleted[\\s_-]scenes?|interviews?|trailers?|bloopers?|outtakes?|shorts?|making[\\s_-]of|bonus)\\b/i;\r\n    parser.addHandler('isExtras', ({ title, result }: HandlerContext) => {\r\n        if (title && result && EXTRAS_PATTERN.test(title)) {\r\n            result.isExtras = true;\r\n        }\r\n    });\r\n\r\n    // --- Episode Title Cleanup ---\r\n    // If we have an episode, try to find the remainder as the episode title\r\n    parser.addHandler('episodeTitle', ({ title, result }: HandlerContext) => {\r\n        if (title && result && result.episode !== undefined) {\r\n            // Look for common separators after the episode number\r\n            const patterns = [\r\n                /[Ss]\\d{1,2}[Ee]\\d{1,3}[\\s._-]+(.*)/,\r\n                /[Ss]\\d{1,2}\\s*-\\s*[Ee]\\d{1,3}[\\s._-]+(.*)/,\r\n                /(?:^|\\s)-\\s*\\d{1,3}\\s*-\\s+(.*)/,\r\n                /\\d{1,2}x\\d{2,3}[\\s._-]+(.*)/,\r\n                /Season\\s+\\d+\\s+Episode\\s+\\d+[\\s._-]+(.*)/\r\n            ];\r\n\r\n            for (const p of patterns) {\r\n                const match = title.match(p);\r\n                if (match && match[1]) {\r\n                    const cleaned = match[1]\r\n                        .replace(/\\.(mkv|mp4|avi|mov|wmv|m4v|ts|m2ts|webm)$/i, '')\r\n                        .trim();\r\n                    result.episodeTitle = cleaned;\r\n                    break;\r\n                }\r\n            }\r\n        }\r\n    });\r\n}\r\n"],"mappings":";AAAA,OAAO,UAAU;AACjB,YAAY,SAAS;;;ACEd,SAAS,oBAAoB,QAAqC;AAErE,SAAO,WAAW,QAAQ,+BAA+B,EAAE,MAAM,WAAW,oBAAoB,KAAK,CAAC;AAGtG,SAAO,WAAW,UAAU,oCAAoC,EAAE,MAAM,UAAU,CAAC;AACnF,SAAO,WAAW,WAAW,oCAAoC,EAAE,MAAM,UAAU,CAAC;AAGpF,SAAO,WAAW,WAAW,iCAAiC,EAAE,MAAM,UAAU,CAAC;AAGjF,SAAO,WAAW,UAAU,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACvE,SAAO,WAAW,WAAW,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGtE,SAAO,WAAW,UAAU,mCAAmC,EAAE,MAAM,UAAU,CAAC;AAClF,SAAO,WAAW,WAAW,mCAAmC,EAAE,MAAM,UAAU,CAAC;AAGnF,SAAO,WAAW,WAAW,8DAA8D,EAAE,MAAM,WAAW,oBAAoB,KAAK,CAAC;AAGxI,QAAM,iBAAiB;AACvB,SAAO,WAAW,YAAY,CAAC,EAAE,OAAO,OAAO,MAAsB;AACjE,QAAI,SAAS,UAAU,eAAe,KAAK,KAAK,GAAG;AAC/C,aAAO,WAAW;AAAA,IACtB;AAAA,EACJ,CAAC;AAID,SAAO,WAAW,gBAAgB,CAAC,EAAE,OAAO,OAAO,MAAsB;AACrE,QAAI,SAAS,UAAU,OAAO,YAAY,QAAW;AAEjD,YAAM,WAAW;AAAA,QACb;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACJ;AAEA,iBAAW,KAAK,UAAU;AACtB,cAAM,QAAQ,MAAM,MAAM,CAAC;AAC3B,YAAI,SAAS,MAAM,CAAC,GAAG;AACnB,gBAAM,UAAU,MAAM,CAAC,EAClB,QAAQ,8CAA8C,EAAE,EACxD,KAAK;AACV,iBAAO,eAAe;AACtB;AAAA,QACJ;AAAA,MACJ;AAAA,IACJ;AAAA,EACJ,CAAC;AACL;;;ADrDO,IAAMA,UAAa;AAG1B,IAAI,gBAA+C;AAK5C,SAAS,mBAA2C;AACvD,MAAI,CAAC,eAAe;AAChB,oBAAgB,IAAQ,WAAmB;AAC3C,IAAI,gBAAY,aAAa;AAC7B,wBAAoB,aAAa;AAAA,EACrC;AACA,SAAO;AACX;AAOO,SAAS,UAAU,UAAkB,UAAyB,CAAC,GAAe;AACjF,QAAM,SAAS,QAAQ,oBAAoB,QAAQ,iBAAiB,IAAI,IAAQ,WAAmB;AAEnG,QAAM,WAAW,KAAK,SAAS,QAAQ;AACvC,QAAM,aAAa,KAAK,QAAQ,QAAQ,MAAM,MAAM,KAAK,SAAS,KAAK,QAAQ,QAAQ,CAAC,IAAI;AAG5F,QAAM,SAAS,OAAO,MAAM,QAAQ;AAIpC,MAAI,OAAO,WAAW,UAAa,YAAY;AAC3C,UAAM,cAAc,WAAW,MAAM,gCAAgC;AACrE,QAAI,aAAa;AACb,aAAO,SAAS,SAAS,YAAY,CAAC,GAAG,EAAE;AAAA,IAC/C;AAAA,EACJ;AAEA,SAAO;AACX;","names":["Parser"]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "parse-torrent-path",
+  "version": "1.0.0",
+  "description": "Modular, handler-based media metadata parser for filenames and paths.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint src test",
+    "format": "prettier --write src test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+  "author": "Charles Aldarondo <charles.aldarondo@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "@vitest/coverage-v8": "^3.0.7",
+    "eslint": "^9.21.0",
+    "prettier": "^3.5.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^3.0.7"
+  },
+  "dependencies": {
+    "parse-torrent-title": "^2.1.0"
+  }
+}