file-lang-map 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Mykhailo Onikiienko
+
+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,150 @@
+# file-lang-map
+
+**Fast, zero-dependency way to identify programming languages from filenames and extensions.**
+
+### Why
+
+Most language detection libraries are either too heavy or too slow (looping over arrays).
+`file-lang-map` pre-indexes GitHub
+Linguist [languages.yml](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml) data into optimized
+hash maps, ensuring instant lookups with a tiny footprint.
+
+## Features
+
+- **O(1) Performance:** Lookups are instant, regardless of how many languages exist.
+- **Browser Ready:** Zero dependencies (no `fs`, no `path`). Works in Vite, Next.js, React, Vue.
+- **Collision Aware:** Correctly handles ambiguous extensions (e.g., `.rs` returns both "Rust" and "RenderScript").
+- **Auto-Updated:** Data is fetched directly from GitHub Linguist sources.
+- **Tiny:** Tree-shakable. Only load what you use.
+
+## Installation
+
+```bash
+npm install file-lang-map
+```
+
+## Usage
+
+### 1. Identify Language by Filename
+
+Handles full paths, exact filenames, and extensions. Returns an array of language names.
+
+```typescript
+import {getLanguageByFileName} from 'file-lang-map';
+
+// Standard extensions
+const langs = getLanguageByFileName('src/app/main.js');
+console.log(langs); // ["JavaScript"]
+
+// Exact filenames
+const docker = getLanguageByFileName('Dockerfile');
+console.log(docker); // ["Dockerfile"]
+
+// Ambiguous extensions (Collision handling)
+const candidates = getLanguageByFileName('lib.rs');
+// Returns: ['RenderScript', 'Rust', 'XML']
+```
+
+### 2. Filter by Type
+
+You can pass a second argument to filter results immediately (e.g., only "programming" languages).
+
+```typescript
+// .h can be C, C++, or Objective-C (all 'programming')
+const headers = getLanguageByFileName('header.h', 'programming');
+// Returns: [ 'C', 'C++', 'Objective-C' ]
+
+// .ts can be TypeScript and XML (XML is "data" type)
+const typescript = getLanguageByFileName('path/to/index.ts', 'programming');
+// Returns: [ 'TypeScript' ]
+
+// .json is 'data', so filtering by 'programming' returns null
+const json = getLanguageByFileName('data.json', 'programming');
+// Returns: null
+```
+
+### 3. Get Language Metadata
+
+Lookup full language details by name (case-insensitive).
+
+```typescript
+import {getLanguage} from 'file-lang-map';
+
+const lang = getLanguage('javascript');
+/*
+{
+  name: 'JavaScript',
+  type: 'programming',
+  extensions: [
+    '.js',         '._js',   '.bones',
+    '.cjs',        '.es',    '.es6',
+    '.frag',       '.gs',    '.jake',
+    '.javascript', '.jsb',   '.jscad',
+    '.jsfl',       '.jslib', '.jsm',
+    '.jspre',      '.jss',   '.jsx',
+    '.mjs',        '.njs',   '.pac',
+    '.sjs',        '.ssjs',  '.xsjs',
+    '.xsjslib'
+  ],
+  filenames: [ 'Jakefile' ]
+}
+*/
+```
+
+### 4. Get All Languages by Type
+
+Useful for filtering lists or building dropdowns.
+
+```typescript
+import {getLanguagesByType} from 'file-lang-map';
+
+const programmingLangs = getLanguagesByType('programming');
+// Returns: [ { name: "JavaScript", type: "programming", ... }, { name: "Python"... }, ... ]
+```
+
+## API Reference
+
+### `getLanguageByFileName(fileName: string, typeFilter?: LanguageType): string[] | null`
+
+Returns an **array of strings** (names).
+
+- **fileName**: Can be a full path, a relative path, or just a filename.
+- **typeFilter**: (Optional) Filter by `'programming' | 'data' | 'markup' | 'prose'`.
+- **Returns**: Array of names or `null` if not found.
+
+### `getLanguage(name: string): Language | null`
+
+Look up a full language object by name. Case-insensitive (`"python"`, `"Python"` work).
+
+- **name**: language name
+- **Returns**: language object
+
+### `getLanguagesByType(type: LanguageType): Language[]`
+
+Get all full language objects belonging to a specific type.
+
+- **type**: `'programming' | 'data' | 'markup' | 'prose'`.
+- **Returns**: Array of language objects.
+
+## Contributing
+
+This package is **self-updating**. The data is fetched from GitHub Linguist automatically.
+To refresh the data locally:
+
+```bash
+npm run generate
+```
+
+## How Self-Updating Works
+
+The project uses a `linguist-lock.json` file to track the state of the upstream `languist.yml` (sha256 hash of
+linguisl.yml).
+
+- When you or CI/CD run `npm run generate`, it downloads the latest data and calculates a hash.
+- If the hash differs from `linguist-lock.json`, the lock file is updated.
+- The CI/CD pipeline (`.github/workflows/update-and-publish.yml)` checks for changes in `linguist-lock.json` to decide
+  whether to release a new version.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,121 @@
+/**
+ * The categories used by GitHub Linguist.
+ */
+type LanguageType = 'data' | 'programming' | 'markup' | 'prose';
+/**
+ * The Language Object returned by the API.
+ */
+interface Language {
+    /**
+     * The pretty display name of the language (e.g., "C++", "JavaScript", "JSON").
+     * Use this for UI labels.
+     */
+    name: string;
+    /**
+     * The category of the language.
+     */
+    type: LanguageType;
+    /**
+     * List of file extensions associated with this language (e.g., [".js", ".mjs"]).
+     */
+    extensions: string[];
+    /**
+     * List of specific filenames associated with this language (e.g., ["Jenkinsfile"]).
+     */
+    filenames: string[];
+    /**
+     * The parent group name, if applicable (e.g., "Shell" for "Alpine Abuild", "TypeScript" for "TSX").
+     * Note: This refers to Linguist's inheritance grouping, not the 'type'.
+     */
+    group?: string;
+}
+
+/**
+ * Get full language metadata by name (case-insensitive lookup).
+ *
+ * @param {string} languageName - The name of the language (e.g., "JavaScript", "python", "TypeScript")
+ * @returns {Language | null} The Language object with metadata, or null if not found
+ *
+ * @example
+ * const lang = getLanguage('javascript');
+ * // => { name: 'JavaScript', type: 'programming', extensions: ['.js', '.mjs', ...], filenames: [...] }
+ *
+ * @example
+ * const lang = getLanguage('PyThOn'); // Case-insensitive
+ * // => { name: 'Python', type: 'programming', extensions: ['.py', ...], filenames: [...] }
+ *
+ * @example
+ * const lang = getLanguage('UnknownLang');
+ * // => null
+ */
+declare function getLanguage(languageName: string): Language | null;
+/**
+ * Get all languages belonging to a specific type category.
+ * Returns an array of full Language objects, not just names.
+ *
+ * @param {LanguageType} type - The category: 'programming' | 'data' | 'markup' | 'prose'
+ * @returns {Language[]} Array of Language objects matching the type, or empty array if none found
+ *
+ * @example
+ * const programmingLangs = getLanguagesByType('programming');
+ * // => [{ name: 'JavaScript', type: 'programming', ... }, { name: 'Python', ... }, ...]
+ *
+ * @example
+ * const dataLangs = getLanguagesByType('data');
+ * // => [{ name: 'JSON', type: 'data', ... }, { name: 'YAML', ... }, ...]
+ *
+ * @example
+ * const markupLangs = getLanguagesByType('markup');
+ * // => [{ name: 'HTML', type: 'markup', ... }, { name: 'XML', ... }, ...]
+ *
+ * @example
+ * // @ts-ignore - invalid type
+ * const invalid = getLanguagesByType('invalid');
+ * // => []
+ */
+declare function getLanguagesByType(type: LanguageType): Language[];
+/**
+ * Get potential language names for a given file path or filename.
+ * Returns an array of language names because some extensions map to multiple languages (e.g., .rs → Rust, RenderScript).
+ * Handles full paths, relative paths, exact filenames (like "Dockerfile"), and extensions.
+ *
+ * @param {string} fileName - File path, relative path, or filename (e.g., "main.ts", "/src/app/main.ts", "Dockerfile")
+ * @param {LanguageType} [typeFilter] - Optional filter by category: 'programming' | 'data' | 'markup' | 'prose'
+ * @returns {string[] | null} Array of language names (e.g., ['JavaScript']) or null if no match found
+ *
+ * @example
+ * getLanguageByFileName('main.js')
+ * // => ['JavaScript']
+ *
+ * @example
+ * getLanguageByFileName('.gitignore')
+ * // => ['Ignore List']
+ *
+ * @example
+ * // Ambiguous extension - returns multiple candidates
+ * getLanguageByFileName('shader.rs')
+ * // => ['RenderScript', 'Rust', 'XML']
+ *
+ * @example
+ * // Windows path with backslashes
+ * getLanguageByFileName('C:\\Users\\Dev\\project\\style.css')
+ * // => ['CSS']
+ *
+ * @example
+ * // Filter excludes non-matching types
+ * getLanguageByFileName('data.json', 'programming')
+ * // => null (JSON is 'data' type, not 'programming')
+ *
+ * @example
+ * // Unknown extension
+ * getLanguageByFileName('file.unknownext')
+ * // => null
+ *
+ * @example
+ * // File without extension (unless exact match)
+ * getLanguageByFileName('random_file_no_ext')
+ * // => null
+ */
+declare function getLanguageByFileName(fileName: string, typeFilter?: LanguageType): string[] | null;
+
+export { getLanguage, getLanguageByFileName, getLanguagesByType };

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The categories used by GitHub Linguist.
+ */
+type LanguageType = 'data' | 'programming' | 'markup' | 'prose';
+/**
+ * The Language Object returned by the API.
+ */
+interface Language {
+    /**
+     * The pretty display name of the language (e.g., "C++", "JavaScript", "JSON").
+     * Use this for UI labels.
+     */
+    name: string;
+    /**
+     * The category of the language.
+     */
+    type: LanguageType;
+    /**
+     * List of file extensions associated with this language (e.g., [".js", ".mjs"]).
+     */
+    extensions: string[];
+    /**
+     * List of specific filenames associated with this language (e.g., ["Jenkinsfile"]).
+     */
+    filenames: string[];
+    /**
+     * The parent group name, if applicable (e.g., "Shell" for "Alpine Abuild", "TypeScript" for "TSX").
+     * Note: This refers to Linguist's inheritance grouping, not the 'type'.
+     */
+    group?: string;
+}
+
+/**
+ * Get full language metadata by name (case-insensitive lookup).
+ *
+ * @param {string} languageName - The name of the language (e.g., "JavaScript", "python", "TypeScript")
+ * @returns {Language | null} The Language object with metadata, or null if not found
+ *
+ * @example
+ * const lang = getLanguage('javascript');
+ * // => { name: 'JavaScript', type: 'programming', extensions: ['.js', '.mjs', ...], filenames: [...] }
+ *
+ * @example
+ * const lang = getLanguage('PyThOn'); // Case-insensitive
+ * // => { name: 'Python', type: 'programming', extensions: ['.py', ...], filenames: [...] }
+ *
+ * @example
+ * const lang = getLanguage('UnknownLang');
+ * // => null
+ */
+declare function getLanguage(languageName: string): Language | null;
+/**
+ * Get all languages belonging to a specific type category.
+ * Returns an array of full Language objects, not just names.
+ *
+ * @param {LanguageType} type - The category: 'programming' | 'data' | 'markup' | 'prose'
+ * @returns {Language[]} Array of Language objects matching the type, or empty array if none found
+ *
+ * @example
+ * const programmingLangs = getLanguagesByType('programming');
+ * // => [{ name: 'JavaScript', type: 'programming', ... }, { name: 'Python', ... }, ...]
+ *
+ * @example
+ * const dataLangs = getLanguagesByType('data');
+ * // => [{ name: 'JSON', type: 'data', ... }, { name: 'YAML', ... }, ...]
+ *
+ * @example
+ * const markupLangs = getLanguagesByType('markup');
+ * // => [{ name: 'HTML', type: 'markup', ... }, { name: 'XML', ... }, ...]
+ *
+ * @example
+ * // @ts-ignore - invalid type
+ * const invalid = getLanguagesByType('invalid');
+ * // => []
+ */
+declare function getLanguagesByType(type: LanguageType): Language[];
+/**
+ * Get potential language names for a given file path or filename.
+ * Returns an array of language names because some extensions map to multiple languages (e.g., .rs → Rust, RenderScript).
+ * Handles full paths, relative paths, exact filenames (like "Dockerfile"), and extensions.
+ *
+ * @param {string} fileName - File path, relative path, or filename (e.g., "main.ts", "/src/app/main.ts", "Dockerfile")
+ * @param {LanguageType} [typeFilter] - Optional filter by category: 'programming' | 'data' | 'markup' | 'prose'
+ * @returns {string[] | null} Array of language names (e.g., ['JavaScript']) or null if no match found
+ *
+ * @example
+ * getLanguageByFileName('main.js')
+ * // => ['JavaScript']
+ *
+ * @example
+ * getLanguageByFileName('.gitignore')
+ * // => ['Ignore List']
+ *
+ * @example
+ * // Ambiguous extension - returns multiple candidates
+ * getLanguageByFileName('shader.rs')
+ * // => ['RenderScript', 'Rust', 'XML']
+ *
+ * @example
+ * // Windows path with backslashes
+ * getLanguageByFileName('C:\\Users\\Dev\\project\\style.css')
+ * // => ['CSS']
+ *
+ * @example
+ * // Filter excludes non-matching types
+ * getLanguageByFileName('data.json', 'programming')
+ * // => null (JSON is 'data' type, not 'programming')
+ *
+ * @example
+ * // Unknown extension
+ * getLanguageByFileName('file.unknownext')
+ * // => null
+ *
+ * @example
+ * // File without extension (unless exact match)
+ * getLanguageByFileName('random_file_no_ext')
+ * // => null
+ */
+declare function getLanguageByFileName(fileName: string, typeFilter?: LanguageType): string[] | null;
+
+export { getLanguage, getLanguageByFileName, getLanguagesByType };