zantetsu 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Zantetsu - Fast anime metadata parser
+ *
+ * JavaScript/TypeScript bindings for the heuristic parser engine.
+ * Provides both a class-based API and convenience functions.
+ * Includes a pure JavaScript fallback when native module is unavailable.
+ */
+import type { HeuristicParserOptions, ParseResult } from './types.js';
+/**
+ * HeuristicParser - Fast regex-based anime filename parser
+ *
+ * Uses optimized regex patterns and scene naming rules for
+ * instant parsing with zero ML overhead.
+ */
+export declare class HeuristicParser {
+    private parser;
+    constructor(_options?: HeuristicParserOptions);
+    parse(input: string): ParseResult;
+    parseBatch(inputs: string[]): ParseResult[];
+}
+/**
+ * Parse a single filename using the default parser
+ */
+export declare function parse(input: string): ParseResult;
+/**
+ * Parse multiple filenames using the default parser
+ */
+export declare function parseBatch(inputs: string[]): ParseResult[];
+/**
+ * Check if native module is being used
+ */
+export declare function isUsingNativeModule(): boolean;
+export type { HeuristicParserOptions, ParseResult, EpisodeSpec, Resolution, VideoCodec, AudioCodec, MediaSource, ParseMode } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,sBAAsB,EACtB,WAAW,EAOZ,MAAM,YAAY,CAAC;AAgSpB;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAwC;gBAE1C,QAAQ,CAAC,EAAE,sBAAsB;IAI7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAcjC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE;CAO5C;AAYD;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,CAE1D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAG7C;AAGD,YAAY,EAAE,sBAAsB,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,321 @@
+/**
+ * Zantetsu - Fast anime metadata parser
+ *
+ * JavaScript/TypeScript bindings for the heuristic parser engine.
+ * Provides both a class-based API and convenience functions.
+ * Includes a pure JavaScript fallback when native module is unavailable.
+ */
+// Track if native module is available
+let useNative = false;
+let nativeModule = null;
+let initialized = false;
+/**
+ * Initialize the native module (done automatically on first use)
+ */
+function initNative() {
+    if (initialized)
+        return;
+    initialized = true;
+    try {
+        // Try to load the native addon
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        nativeModule = require('@zan/heuristic-node');
+        useNative = true;
+    }
+    catch {
+        // Use JavaScript fallback
+        nativeModule = null;
+        useNative = false;
+    }
+}
+/**
+ * JavaScript-only fallback parser using regex patterns
+ * Matches the HeuristicParser from the Rust crate
+ */
+class JsHeuristicParser {
+    // Simplified regex patterns
+    reResolution = /1080p|720p|480p|2160p/i;
+    reGroup = /^\[([^\]]+)\]/;
+    // Match episode after dash, space, or dot - but not after year
+    reEpisode = /(?:[\s\-.])(?:[Ee]p?\.?)?\s*(\d{1,4})(?:\b|v\d|[^\d])/;
+    reEpisodeV = /(?:[\s\-.])(?:[Ee]p?\.?)?\s*(\d{1,4})v(\d+)/i;
+    reEpisodeRange = /(?:[\s\-.])(?:[Ee]p?\.?)?\s*(\d{1,4})\s*[-~]\s*(\d{1,4})/i;
+    reSeason = /(?:^|[\s\-])S(\d+)/i;
+    reYear = /\((\d{4})\)/;
+    reExtension = /\.(\w+)$/;
+    reCrc32 = /\[([A-Fa-f0-9]{8})\]/;
+    parse(input) {
+        const trimmed = input.trim();
+        if (!trimmed) {
+            throw new Error('input is empty or whitespace-only');
+        }
+        const result = {
+            input: trimmed,
+            title: null,
+            group: null,
+            episode: null,
+            season: null,
+            resolution: null,
+            video_codec: null,
+            audio_codec: null,
+            source: null,
+            year: null,
+            crc32: null,
+            extension: null,
+            version: null,
+            confidence: 0,
+            parse_mode: 'Light',
+        };
+        // Extract basic fields
+        result.group = this.extractGroup(trimmed);
+        result.extension = this.extractExtension(trimmed);
+        result.crc32 = this.extractCrc32(trimmed);
+        result.resolution = this.extractResolution(trimmed);
+        result.season = this.extractSeason(trimmed);
+        result.year = this.extractYear(trimmed);
+        result.episode = this.extractEpisode(trimmed);
+        // Extract title
+        result.title = this.extractTitle(trimmed, result);
+        // Compute confidence
+        result.confidence = this.computeConfidence(result);
+        return result;
+    }
+    extractGroup(input) {
+        const match = this.reGroup.exec(input);
+        return match ? match[1].trim() : null;
+    }
+    extractExtension(input) {
+        const match = this.reExtension.exec(input);
+        return match ? match[1].toLowerCase() : null;
+    }
+    extractCrc32(input) {
+        const match = this.reCrc32.exec(input);
+        return match ? match[1].toUpperCase() : null;
+    }
+    extractResolution(input) {
+        if (input.includes('2160p') || input.includes('2160i'))
+            return 'UHD2160';
+        if (input.includes('1080p') || input.includes('1080i'))
+            return 'FHD1080';
+        if (input.includes('720p') || input.includes('720i'))
+            return 'HD720';
+        if (input.includes('480p') || input.includes('480i'))
+            return 'SD480';
+        return null;
+    }
+    extractSeason(input) {
+        const match = this.reSeason.exec(input);
+        return match ? parseInt(match[1], 10) : null;
+    }
+    extractYear(input) {
+        const match = this.reYear.exec(input);
+        return match ? parseInt(match[1], 10) : null;
+    }
+    extractEpisode(input) {
+        // Try versioned episode
+        let match = this.reEpisodeV.exec(input);
+        if (match) {
+            return { type: 'versioned', episode: parseInt(match[1], 10), version: parseInt(match[2], 10) };
+        }
+        // Try episode range
+        match = this.reEpisodeRange.exec(input);
+        if (match) {
+            const start = parseInt(match[1], 10);
+            const end = parseInt(match[2], 10);
+            if (start < end) {
+                return { type: 'range', start, end };
+            }
+        }
+        // Try single episode
+        match = this.reEpisode.exec(input);
+        if (match) {
+            return { type: 'single', episode: parseInt(match[1], 10) };
+        }
+        return null;
+    }
+    extractTitle(input, result) {
+        let work = input;
+        // Remove group tag
+        if (result.group) {
+            const groupIdx = work.indexOf(']');
+            if (groupIdx !== -1) {
+                work = work.substring(groupIdx + 1);
+            }
+        }
+        // Remove extension
+        if (result.extension) {
+            const extPos = work.lastIndexOf(`.${result.extension}`);
+            if (extPos !== -1) {
+                work = work.substring(0, extPos);
+            }
+        }
+        // Remove episode info
+        work = work.replace(this.reEpisodeV, ' ');
+        work = work.replace(this.reEpisodeRange, ' ');
+        work = work.replace(this.reEpisode, ' ');
+        work = work.replace(this.reSeason, ' ');
+        work = work.replace(this.reYear, ' ');
+        // Remove bracketed content
+        work = work.replace(/\[[^\]]*\]/g, ' ');
+        work = work.replace(/\([^\)]*\)/g, ' ');
+        // Clean up
+        const cleaned = work
+            .replace(/[._]/g, ' ')
+            .replace(/-/g, ' ')
+            .split(/\s+/)
+            .filter(Boolean)
+            .join(' ')
+            .trim();
+        return cleaned || null;
+    }
+    computeConfidence(result) {
+        let fieldsPresent = 0;
+        let fieldsTotal = 7;
+        if (result.title) {
+            fieldsPresent += 2;
+            fieldsTotal += 1;
+        }
+        if (result.group)
+            fieldsPresent += 1;
+        if (result.episode)
+            fieldsPresent += 1;
+        if (result.resolution)
+            fieldsPresent += 1;
+        if (result.video_codec)
+            fieldsPresent += 1;
+        if (result.audio_codec)
+            fieldsPresent += 1;
+        if (result.source)
+            fieldsPresent += 1;
+        return Math.min(fieldsPresent / fieldsTotal, 1.0);
+    }
+}
+// Singleton instances
+let jsParser = null;
+let nativeParser = null;
+function getParser() {
+    initNative();
+    if (useNative) {
+        if (!nativeParser) {
+            // eslint-disable-next-line new-cap
+            nativeParser = new nativeModule.HeuristicParser();
+        }
+        return nativeParser;
+    }
+    if (!jsParser) {
+        jsParser = new JsHeuristicParser();
+    }
+    return jsParser;
+}
+/**
+ * Convert native episode spec to typed EpisodeSpec
+ */
+function convertEpisodeSpec(native) {
+    if (!native)
+        return null;
+    if (typeof native === 'number') {
+        return { type: 'single', episode: native };
+    }
+    const n = native;
+    if (typeof n.type === 'number') {
+        switch (n.type) {
+            case 0:
+                return { type: 'single', episode: n.episode };
+            case 1:
+                return { type: 'range', start: n.start, end: n.end };
+            case 2:
+                return { type: 'multi', episodes: n.episodes };
+            case 3:
+                return { type: 'versioned', episode: n.episode, version: n.version };
+        }
+    }
+    if (n.episode !== undefined && n.version !== undefined) {
+        return { type: 'versioned', episode: n.episode, version: n.version };
+    }
+    if (n.start !== undefined && n.end !== undefined) {
+        return { type: 'range', start: n.start, end: n.end };
+    }
+    if (n.episodes !== undefined) {
+        return { type: 'multi', episodes: n.episodes };
+    }
+    return null;
+}
+/**
+ * Convert native parse result to typed ParseResult
+ */
+function convertResult(native) {
+    const n = native;
+    return {
+        input: n.input,
+        title: n.title,
+        group: n.group,
+        episode: convertEpisodeSpec(n.episode),
+        season: n.season,
+        resolution: n.resolution,
+        video_codec: n.video_codec,
+        audio_codec: n.audio_codec,
+        source: n.source,
+        year: n.year,
+        crc32: n.crc32,
+        extension: n.extension,
+        version: n.version,
+        confidence: n.confidence,
+        parse_mode: n.parse_mode,
+    };
+}
+/**
+ * HeuristicParser - Fast regex-based anime filename parser
+ *
+ * Uses optimized regex patterns and scene naming rules for
+ * instant parsing with zero ML overhead.
+ */
+export class HeuristicParser {
+    parser;
+    constructor(_options) {
+        this.parser = getParser();
+    }
+    parse(input) {
+        if (typeof input !== 'string' || !input.trim()) {
+            throw new Error('Input must be a non-empty string');
+        }
+        const result = this.parser.parse(input);
+        if (!useNative) {
+            return result;
+        }
+        return convertResult(result);
+    }
+    parseBatch(inputs) {
+        if (!Array.isArray(inputs)) {
+            throw new Error('Input must be an array of strings');
+        }
+        return inputs.map(input => this.parse(input));
+    }
+}
+// Default parser instance for convenience functions
+let defaultParser = null;
+function getDefaultParser() {
+    if (!defaultParser) {
+        defaultParser = new HeuristicParser();
+    }
+    return defaultParser;
+}
+/**
+ * Parse a single filename using the default parser
+ */
+export function parse(input) {
+    return getDefaultParser().parse(input);
+}
+/**
+ * Parse multiple filenames using the default parser
+ */
+export function parseBatch(inputs) {
+    return getDefaultParser().parseBatch(inputs);
+}
+/**
+ * Check if native module is being used
+ */
+export function isUsingNativeModule() {
+    initNative();
+    return useNative;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/jest.config.js

@@ -0,0 +1,24 @@
+export default {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: {
+          module: 'ES2022',
+          moduleResolution: 'bundler',
+        },
+      },
+    ],
+  },
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
+  coverageDirectory: 'coverage',
+  testTimeout: 10000,
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "zantetsu",
+  "version": "0.1.0",
+  "description": "Fast anime metadata parser - extracts title, episode, resolution, codecs from filenames",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "anime",
+    "parser",
+    "metadata",
+    "torrent",
+    "filename",
+    "heuristic"
+  ],
+  "author": "kokoro",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/enrell/zantetsu"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Zantetsu - Jest test suite for heuristic parser
+ */
+
+import { HeuristicParser, parse, parseBatch } from '../src/index.js';
+
+describe('HeuristicParser', () => {
+  let parser: HeuristicParser;
+
+  beforeAll(() => {
+    parser = new HeuristicParser();
+  });
+
+  describe('constructor', () => {
+    it('should create a parser instance', () => {
+      expect(parser).toBeDefined();
+    });
+
+    it('should accept options', () => {
+      const parserWithOptions = new HeuristicParser({ debug: true });
+      expect(parserWithOptions).toBeDefined();
+    });
+  });
+
+  describe('parse()', () => {
+    it('should parse SubsPlease format correctly', () => {
+      const result = parser.parse('[SubsPlease] Jujutsu Kaisen - 24 (1080p) [A1B2C3D4].mkv');
+
+      expect(result.title).toBe('Jujutsu Kaisen');
+      expect(result.group).toBe('SubsPlease');
+      expect(result.episode).toEqual({ type: 'single', episode: 24 });
+      expect(result.resolution).toBe('FHD1080');
+      expect(result.crc32).toBe('A1B2C3D4');
+      expect(result.extension).toBe('mkv');
+      expect(result.confidence).toBeGreaterThan(0.5);
+    });
+
+    it('should parse Erai-raws versioned episode format', () => {
+      const result = parser.parse(
+        '[Erai-raws] Shingeki no Kyojin - The Final Season - 28v2 [1080p][HEVC].mkv'
+      );
+
+      expect(result.group).toBe('Erai-raws');
+      expect(result.episode).toEqual({ type: 'versioned', episode: 28, version: 2 });
+      expect(result.resolution).toBe('FHD1080');
+      expect(result.video_codec).toBe('HEVC');
+    });
+
+    it('should parse batch episode range', () => {
+      const result = parser.parse('[Judas] Golden Kamuy S3 - 01-12 (1080p) [Batch]');
+
+      expect(result.group).toBe('Judas');
+      expect(result.season).toBe(3);
+      expect(result.episode).toEqual({ type: 'range', start: 1, end: 12 });
+      expect(result.resolution).toBe('FHD1080');
+    });
+
+    it('should parse dot-separated format', () => {
+      const result = parser.parse('One.Piece.1084.VOSTFR.1080p.WEB.x264-AAC.mkv');
+
+      expect(result.title).toBe('One Piece');
+      expect(result.episode).toEqual({ type: 'single', episode: 1084 });
+      expect(result.resolution).toBe('FHD1080');
+      expect(result.video_codec).toBe('H264');
+      expect(result.audio_codec).toBe('AAC');
+    });
+
+    it('should handle various resolutions', () => {
+      const res480 = parser.parse('[Test] Show - 01 (480p).mkv');
+      expect(res480.resolution).toBe('SD480');
+
+      const res720 = parser.parse('[Test] Show - 01 (720p).mkv');
+      expect(res720.resolution).toBe('HD720');
+
+      const res1080 = parser.parse('[Test] Show - 01 (1080p).mkv');
+      expect(res1080.resolution).toBe('FHD1080');
+
+      const res2160 = parser.parse('[Test] Show - 01 (2160p).mkv');
+      expect(res2160.resolution).toBe('UHD2160');
+    });
+
+    it('should extract video codecs', () => {
+      expect(parser.parse('[G] Title - 01 [x264].mkv').video_codec).toBe('H264');
+      expect(parser.parse('[G] Title - 01 [x265].mkv').video_codec).toBe('HEVC');
+      expect(parser.parse('[G] Title - 01 [HEVC].mkv').video_codec).toBe('HEVC');
+      expect(parser.parse('[G] Title - 01 [AV1].mkv').video_codec).toBe('AV1');
+      expect(parser.parse('[G] Title - 01 [VP9].mkv').video_codec).toBe('VP9');
+    });
+
+    it('should extract audio codecs', () => {
+      expect(parser.parse('[G] Title - 01 [FLAC].mkv').audio_codec).toBe('FLAC');
+      expect(parser.parse('[G] Title - 01 [AAC].mkv').audio_codec).toBe('AAC');
+      expect(parser.parse('[G] Title - 01 [Opus].mkv').audio_codec).toBe('Opus');
+      expect(parser.parse('[G] Title - 01 [AC3].mkv').audio_codec).toBe('AC3');
+    });
+
+    it('should extract media sources', () => {
+      expect(parser.parse('[G] Title - 01 Blu-ray 1080p.mkv').source).toBe('BluRay');
+      expect(parser.parse('[G] Title - 01 WEB-DL 1080p.mkv').source).toBe('WebDL');
+      expect(parser.parse('[G] Title - 01 HDTV 720p.mkv').source).toBe('HDTV');
+    });
+
+    it('should extract year', () => {
+      const result = parser.parse('[Group] Title (2024) - 01 (1080p).mkv');
+      expect(result.year).toBe(2024);
+    });
+
+    it('should compute confidence based on extracted fields', () => {
+      // Minimal parse - only title
+      const minimal = parser.parse('Some Random Title.mkv');
+      expect(minimal.confidence).toBeLessThan(0.5);
+
+      // Rich parse - many fields
+      const rich = parser.parse(
+        '[SubsPlease] Jujutsu Kaisen - 24 (1080p) [H264] [AAC] [A1B2C3D4].mkv'
+      );
+      expect(rich.confidence).toBeGreaterThan(0.7);
+    });
+
+    it('should throw on empty input', () => {
+      expect(() => parser.parse('')).toThrow();
+      expect(() => parser.parse('   ')).toThrow();
+    });
+
+    it('should return correct parse mode', () => {
+      const result = parser.parse('[Test] Title - 01 (1080p).mkv');
+      expect(result.parse_mode).toBe('Light');
+    });
+  });
+
+  describe('parseBatch()', () => {
+    it('should parse multiple inputs', () => {
+      const inputs = [
+        '[SubsPlease] Jujutsu Kaisen - 24 (1080p).mkv',
+        '[Erai-raws] One Piece - 1000 [1080p].mkv',
+        'Anime.Title.01.720p.WEB.x264.mkv',
+      ];
+
+      const results = parser.parseBatch(inputs);
+
+      expect(results).toHaveLength(3);
+      expect(results[0].title).toBe('Jujutsu Kaisen');
+      expect(results[1].title).toBe('One Piece');
+      expect(results[2].title).toBe('Anime Title');
+    });
+  });
+});
+
+describe('Convenience functions', () => {
+  describe('parse()', () => {
+    it('should work as a convenience function', () => {
+      const result = parse('[Test] Anime - 01 (1080p).mkv');
+      expect(result.title).toBe('Anime');
+      expect(result.episode).toEqual({ type: 'single', episode: 1 });
+    });
+  });
+
+  describe('parseBatch()', () => {
+    it('should work as a convenience function', () => {
+      const results = parseBatch(['[Test] A - 01.mkv', '[Test] B - 02.mkv']);
+      expect(results).toHaveLength(2);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,376 @@
+/**
+ * Zantetsu - Fast anime metadata parser
+ *
+ * JavaScript/TypeScript bindings for the heuristic parser engine.
+ * Provides both a class-based API and convenience functions.
+ * Includes a pure JavaScript fallback when native module is unavailable.
+ */
+
+// Import types from the declaration file
+import type { 
+  HeuristicParserOptions, 
+  ParseResult, 
+  EpisodeSpec,
+  Resolution,
+  VideoCodec,
+  AudioCodec,
+  MediaSource,
+  ParseMode
+} from './types.js';
+
+// Track if native module is available
+let useNative = false;
+let nativeModule: unknown = null;
+let initialized = false;
+
+/**
+ * Initialize the native module (done automatically on first use)
+ */
+function initNative(): void {
+  if (initialized) return;
+  initialized = true;
+
+  try {
+    // Try to load the native addon
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    nativeModule = require('@zan/heuristic-node');
+    useNative = true;
+  } catch {
+    // Use JavaScript fallback
+    nativeModule = null;
+    useNative = false;
+  }
+}
+
+/**
+ * JavaScript-only fallback parser using regex patterns
+ * Matches the HeuristicParser from the Rust crate
+ */
+class JsHeuristicParser {
+  // Simplified regex patterns
+  private readonly reResolution = /1080p|720p|480p|2160p/i;
+  private readonly reGroup = /^\[([^\]]+)\]/;
+  // Match episode after dash, space, or dot - but not after year
+  private readonly reEpisode = /(?:[\s\-.])(?:[Ee]p?\.?)?\s*(\d{1,4})(?:\b|v\d|[^\d])/;
+  private readonly reEpisodeV = /(?:[\s\-.])(?:[Ee]p?\.?)?\s*(\d{1,4})v(\d+)/i;
+  private readonly reEpisodeRange = /(?:[\s\-.])(?:[Ee]p?\.?)?\s*(\d{1,4})\s*[-~]\s*(\d{1,4})/i;
+  private readonly reSeason = /(?:^|[\s\-])S(\d+)/i;
+  private readonly reYear = /\((\d{4})\)/;
+  private readonly reExtension = /\.(\w+)$/;
+  private readonly reCrc32 = /\[([A-Fa-f0-9]{8})\]/;
+
+  parse(input: string): ParseResult {
+    const trimmed = input.trim();
+    if (!trimmed) {
+      throw new Error('input is empty or whitespace-only');
+    }
+
+    const result: ParseResult = {
+      input: trimmed,
+      title: null,
+      group: null,
+      episode: null,
+      season: null,
+      resolution: null,
+      video_codec: null,
+      audio_codec: null,
+      source: null,
+      year: null,
+      crc32: null,
+      extension: null,
+      version: null,
+      confidence: 0,
+      parse_mode: 'Light',
+    };
+
+    // Extract basic fields
+    result.group = this.extractGroup(trimmed);
+    result.extension = this.extractExtension(trimmed);
+    result.crc32 = this.extractCrc32(trimmed);
+    result.resolution = this.extractResolution(trimmed);
+    result.season = this.extractSeason(trimmed);
+    result.year = this.extractYear(trimmed);
+    result.episode = this.extractEpisode(trimmed);
+
+    // Extract title
+    result.title = this.extractTitle(trimmed, result);
+
+    // Compute confidence
+    result.confidence = this.computeConfidence(result);
+
+    return result;
+  }
+
+  private extractGroup(input: string): string | null {
+    const match = this.reGroup.exec(input);
+    return match ? match[1].trim() : null;
+  }
+
+  private extractExtension(input: string): string | null {
+    const match = this.reExtension.exec(input);
+    return match ? match[1].toLowerCase() : null;
+  }
+
+  private extractCrc32(input: string): string | null {
+    const match = this.reCrc32.exec(input);
+    return match ? match[1].toUpperCase() : null;
+  }
+
+  private extractResolution(input: string): Resolution | null {
+    if (input.includes('2160p') || input.includes('2160i')) return 'UHD2160';
+    if (input.includes('1080p') || input.includes('1080i')) return 'FHD1080';
+    if (input.includes('720p') || input.includes('720i')) return 'HD720';
+    if (input.includes('480p') || input.includes('480i')) return 'SD480';
+    return null;
+  }
+
+  private extractSeason(input: string): number | null {
+    const match = this.reSeason.exec(input);
+    return match ? parseInt(match[1], 10) : null;
+  }
+
+  private extractYear(input: string): number | null {
+    const match = this.reYear.exec(input);
+    return match ? parseInt(match[1], 10) : null;
+  }
+
+  private extractEpisode(input: string): EpisodeSpec | null {
+    // Try versioned episode
+    let match = this.reEpisodeV.exec(input);
+    if (match) {
+      return { type: 'versioned', episode: parseInt(match[1], 10), version: parseInt(match[2], 10) };
+    }
+
+    // Try episode range
+    match = this.reEpisodeRange.exec(input);
+    if (match) {
+      const start = parseInt(match[1], 10);
+      const end = parseInt(match[2], 10);
+      if (start < end) {
+        return { type: 'range', start, end };
+      }
+    }
+
+    // Try single episode
+    match = this.reEpisode.exec(input);
+    if (match) {
+      return { type: 'single', episode: parseInt(match[1], 10) };
+    }
+
+    return null;
+  }
+
+  private extractTitle(input: string, result: ParseResult): string | null {
+    let work = input;
+
+    // Remove group tag
+    if (result.group) {
+      const groupIdx = work.indexOf(']');
+      if (groupIdx !== -1) {
+        work = work.substring(groupIdx + 1);
+      }
+    }
+
+    // Remove extension
+    if (result.extension) {
+      const extPos = work.lastIndexOf(`.${result.extension}`);
+      if (extPos !== -1) {
+        work = work.substring(0, extPos);
+      }
+    }
+
+    // Remove episode info
+    work = work.replace(this.reEpisodeV, ' ');
+    work = work.replace(this.reEpisodeRange, ' ');
+    work = work.replace(this.reEpisode, ' ');
+    work = work.replace(this.reSeason, ' ');
+    work = work.replace(this.reYear, ' ');
+
+    // Remove bracketed content
+    work = work.replace(/\[[^\]]*\]/g, ' ');
+    work = work.replace(/\([^\)]*\)/g, ' ');
+
+    // Clean up
+    const cleaned = work
+      .replace(/[._]/g, ' ')
+      .replace(/-/g, ' ')
+      .split(/\s+/)
+      .filter(Boolean)
+      .join(' ')
+      .trim();
+
+    return cleaned || null;
+  }
+
+  private computeConfidence(result: ParseResult): number {
+    let fieldsPresent = 0;
+    let fieldsTotal = 7;
+
+    if (result.title) {
+      fieldsPresent += 2;
+      fieldsTotal += 1;
+    }
+    if (result.group) fieldsPresent += 1;
+    if (result.episode) fieldsPresent += 1;
+    if (result.resolution) fieldsPresent += 1;
+    if (result.video_codec) fieldsPresent += 1;
+    if (result.audio_codec) fieldsPresent += 1;
+    if (result.source) fieldsPresent += 1;
+
+    return Math.min(fieldsPresent / fieldsTotal, 1.0);
+  }
+}
+
+// Singleton instances
+let jsParser: JsHeuristicParser | null = null;
+let nativeParser: unknown = null;
+
+function getParser(): { parse: (input: string) => unknown } {
+  initNative();
+
+  if (useNative) {
+    if (!nativeParser) {
+      // eslint-disable-next-line new-cap
+      nativeParser = new (nativeModule as { HeuristicParser: new () => { parse: (s: string) => unknown } }).HeuristicParser();
+    }
+    return nativeParser as { parse: (s: string) => unknown };
+  }
+
+  if (!jsParser) {
+    jsParser = new JsHeuristicParser();
+  }
+  return jsParser;
+}
+
+/**
+ * Convert native episode spec to typed EpisodeSpec
+ */
+function convertEpisodeSpec(native: unknown): EpisodeSpec | null {
+  if (!native) return null;
+
+  if (typeof native === 'number') {
+    return { type: 'single', episode: native };
+  }
+
+  const n = native as Record<string, unknown>;
+
+  if (typeof n.type === 'number') {
+    switch (n.type) {
+      case 0:
+        return { type: 'single', episode: n.episode as number };
+      case 1:
+        return { type: 'range', start: n.start as number, end: n.end as number };
+      case 2:
+        return { type: 'multi', episodes: n.episodes as number[] };
+      case 3:
+        return { type: 'versioned', episode: n.episode as number, version: n.version as number };
+    }
+  }
+
+  if (n.episode !== undefined && n.version !== undefined) {
+    return { type: 'versioned', episode: n.episode as number, version: n.version as number };
+  }
+  if (n.start !== undefined && n.end !== undefined) {
+    return { type: 'range', start: n.start as number, end: n.end as number };
+  }
+  if (n.episodes !== undefined) {
+    return { type: 'multi', episodes: n.episodes as number[] };
+  }
+
+  return null;
+}
+
+/**
+ * Convert native parse result to typed ParseResult
+ */
+function convertResult(native: unknown): ParseResult {
+  const n = native as Record<string, unknown>;
+  return {
+    input: n.input as string,
+    title: n.title as string | null,
+    group: n.group as string | null,
+    episode: convertEpisodeSpec(n.episode),
+    season: n.season as number | null,
+    resolution: n.resolution as Resolution | null,
+    video_codec: n.video_codec as VideoCodec | null,
+    audio_codec: n.audio_codec as AudioCodec | null,
+    source: n.source as MediaSource | null,
+    year: n.year as number | null,
+    crc32: n.crc32 as string | null,
+    extension: n.extension as string | null,
+    version: n.version as number | null,
+    confidence: n.confidence as number,
+    parse_mode: n.parse_mode as ParseMode,
+  };
+}
+
+/**
+ * HeuristicParser - Fast regex-based anime filename parser
+ *
+ * Uses optimized regex patterns and scene naming rules for
+ * instant parsing with zero ML overhead.
+ */
+export class HeuristicParser {
+  private parser: { parse: (input: string) => unknown };
+
+  constructor(_options?: HeuristicParserOptions) {
+    this.parser = getParser();
+  }
+
+  parse(input: string): ParseResult {
+    if (typeof input !== 'string' || !input.trim()) {
+      throw new Error('Input must be a non-empty string');
+    }
+
+    const result = this.parser.parse(input);
+
+    if (!useNative) {
+      return result as ParseResult;
+    }
+
+    return convertResult(result);
+  }
+
+  parseBatch(inputs: string[]): ParseResult[] {
+    if (!Array.isArray(inputs)) {
+      throw new Error('Input must be an array of strings');
+    }
+
+    return inputs.map(input => this.parse(input));
+  }
+}
+
+// Default parser instance for convenience functions
+let defaultParser: HeuristicParser | null = null;
+
+function getDefaultParser(): HeuristicParser {
+  if (!defaultParser) {
+    defaultParser = new HeuristicParser();
+  }
+  return defaultParser;
+}
+
+/**
+ * Parse a single filename using the default parser
+ */
+export function parse(input: string): ParseResult {
+  return getDefaultParser().parse(input);
+}
+
+/**
+ * Parse multiple filenames using the default parser
+ */
+export function parseBatch(inputs: string[]): ParseResult[] {
+  return getDefaultParser().parseBatch(inputs);
+}
+
+/**
+ * Check if native module is being used
+ */
+export function isUsingNativeModule(): boolean {
+  initNative();
+  return useNative;
+}
+
+// Export types
+export type { HeuristicParserOptions, ParseResult, EpisodeSpec, Resolution, VideoCodec, AudioCodec, MediaSource, ParseMode } from './types.js';

package/src/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Zantetsu - Fast anime metadata parser
+ *
+ * Type definitions for the heuristic parser bindings
+ */
+
+/**
+ * Episode specification types
+ */
+export type EpisodeSpec =
+  | { type: 'single'; episode: number }
+  | { type: 'range'; start: number; end: number }
+  | { type: 'multi'; episodes: number[] }
+  | { type: 'versioned'; episode: number; version: number };
+
+/**
+ * Video resolution
+ */
+export type Resolution = 'SD480' | 'HD720' | 'FHD1080' | 'UHD2160';
+
+/**
+ * Video codec
+ */
+export type VideoCodec = 'H264' | 'HEVC' | 'AV1' | 'VP9' | 'MPEG4';
+
+/**
+ * Audio codec
+ */
+export type AudioCodec = 'FLAC' | 'AAC' | 'Opus' | 'AC3' | 'DTS' | 'MP3' | 'Vorbis' | 'TrueHD' | 'EAAC';
+
+/**
+ * Media source
+ */
+export type MediaSource = 'BluRayRemux' | 'BluRay' | 'WebDL' | 'WebRip' | 'HDTV' | 'DVD' | 'LaserDisc' | 'VHS';
+
+/**
+ * Parse mode
+ */
+export type ParseMode = 'Full' | 'Light' | 'Auto';
+
+/**
+ * Options for creating a HeuristicParser
+ */
+export interface HeuristicParserOptions {
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+/**
+ * Parse result from the heuristic parser
+ */
+export interface ParseResult {
+  /** Original input string */
+  input: string;
+  /** Extracted anime title (normalized) */
+  title: string | null;
+  /** Release group name (e.g., "SubsPlease", "Erai-raws") */
+  group: string | null;
+  /** Episode specification */
+  episode: EpisodeSpec | null;
+  /** Season number */
+  season: number | null;
+  /** Video resolution */
+  resolution: Resolution | null;
+  /** Video codec */
+  video_codec: VideoCodec | null;
+  /** Audio codec */
+  audio_codec: AudioCodec | null;
+  /** Media source */
+  source: MediaSource | null;
+  /** Release year */
+  year: number | null;
+  /** CRC32 checksum (hex string) */
+  crc32: string | null;
+  /** File extension (without leading dot) */
+  extension: string | null;
+  /** Release version (e.g., v2 = 2) */
+  version: number | null;
+  /** Confidence score in [0.0, 1.0] */
+  confidence: number;
+  /** Parse mode used */
+  parse_mode: ParseMode;
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "noEmit": false,
+    "target": "ES2022"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}