file-lang-map 1.0.0 → 1.1.1

package/README.md

@@ -1,21 +1,22 @@
 # file-lang-map
 
-**Fast, zero-dependency way to identify programming languages from filenames and extensions.**
+**Fast, zero-dependency way to identify programming languages from paths, filenames, and extensions.**
 
-### Why
+## 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.
+Some language detectors can be heavy or rely on linear scans. `file-lang-map` pre-indexes GitHub
+Linguist [languages.yml](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml) into compact lookup
+maps, giving near-instant lookups, a small bundle size, and zero runtime dependencies.
 
 ## 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.
+- **O(1) (average-case) Performance:** Lookups are instant, regardless of how many languages exist.
+- **Browser Ready:** Zero runtime dependencies. Works in browser and Node.js.
+- **TypeScript Support:** Includes built-in type definitions.
+- **Flexible:** Works with full and relative paths, filenames, or just extensions for all platforms.
+- **Tiny:** Tree-shakable. Only load what you use. (Use named imports and a bundler that supports tree-shaking)
+- **Collision Aware:** Correctly handles ambiguous extensions (e.g., `.h` returns "C", "C++" and "Objective-C").
+- **Auto-Updated:** Data is fetched directly from GitHub Linguist sources using GitHub actions weekly.
 
 ## Installation
 
@@ -23,11 +24,45 @@ hash maps, ensuring instant lookups with a tiny footprint.
 npm install file-lang-map
 ```
 
-## Usage
+## Quick Start
+
+```typescript
+import {getLanguageByFileName, getLanguage, getLanguagesByType} from 'file-lang-map';
+
+// Get all possible languages from filename (may return null if unknown)
+const languages = getLanguageByFileName('path/to/file.js');
+if (languages === null) {
+  console.log('not found')
+} else {
+  console.log(languages)
+  // ['JavaScript']
+}
+
+// Get language metadata by name. Case-insensitive lookup ("javascript" or "JavaScript").
+const language = getLanguage('JavaScript');
+/*
+{
+  name: 'JavaScript',
+  type: 'programming',
+  extensions: ['.js', '.cjs', '.mjs', ... ], // list of all know extensions
+  filenames: ['Jakefile'] // list of all known filenames
+}
+*/
+
+// You can optionally filter results by type (e.g., only 'programming')
+const prog = getLanguageByFileName('data.json', 'programming');
+// prog === null because JSON is a 'data' type
+
+// Get list of all known "programming" languages (also available - 'data', 'markup', 'prose')
+const programmingLanguages = getLanguagesByType('programming');
+// ['JavaScript', 'Python', 'TypeScript', 'Rust', ...]
+```
+
+## Examples
 
 ### 1. Identify Language by Filename
 
-Handles full paths, exact filenames, and extensions. Returns an array of language names.
+Handles full paths (absolute or relative), exact filenames, and extensions. Returns an array of language names.
 
 ```typescript
 import {getLanguageByFileName} from 'file-lang-map';
@@ -66,10 +101,13 @@ const json = getLanguageByFileName('data.json', 'programming');
 ### 3. Get Language Metadata
 
 Lookup full language details by name (case-insensitive).
+Language object includes all possible extensions for the language, name, possible filenames, and type.
 
 ```typescript
 import {getLanguage} from 'file-lang-map';
 
+// Case-insensitive lookup. 
+// Returns language object which includes all possible extensions for the language, name...
 const lang = getLanguage('javascript');
 /*
 {
@@ -93,13 +131,16 @@ const lang = getLanguage('javascript');
 
 ### 4. Get All Languages by Type
 
-Useful for filtering lists or building dropdowns.
+Useful for filtering lists or building dropdowns. Returns an array of language names (strings).
 
 ```typescript
 import {getLanguagesByType} from 'file-lang-map';
 
 const programmingLangs = getLanguagesByType('programming');
-// Returns: [ { name: "JavaScript", type: "programming", ... }, { name: "Python"... }, ... ]
+// Returns: ['JavaScript', 'Python', 'TypeScript', 'Rust', ...]
+
+const dataLangs = getLanguagesByType('data');
+// Returns: ['JSON', 'YAML', 'CSV', 'TOML', ...]
 ```
 
 ## API Reference
@@ -119,14 +160,14 @@ Look up a full language object by name. Case-insensitive (`"python"`, `"Python"`
 - **name**: language name
 - **Returns**: language object
 
-### `getLanguagesByType(type: LanguageType): Language[]`
+### `getLanguagesByType(type: LanguageType): string[]`
 
-Get all full language objects belonging to a specific type.
+Get all language names belonging to a specific type.
 
 - **type**: `'programming' | 'data' | 'markup' | 'prose'`.
-- **Returns**: Array of language objects.
+- **Returns**: Array of language names (strings).
 
-## Contributing
+## Contributing and Development
 
 This package is **self-updating**. The data is fetched from GitHub Linguist automatically.
 To refresh the data locally:
@@ -135,12 +176,21 @@ To refresh the data locally:
 npm run generate
 ```
 
-## How Self-Updating Works
+### Running Tests
+
+The project has two test commands:
+
+- **`npm test`**: Uses native Node.js glob patterns (`test/**/*.test.ts`). Requires Node.js 20.11+ or 22+.
+- **`npm run test:ci`**: Uses shell `find` command for file discovery. Compatible with Node.js 18+.
+
+The CI pipeline tests on Node 18 and 24, so `test:ci` ensures compatibility with older Node versions that don't support
+glob patterns in the `--test` flag.
+
+### 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).
+The project creates and uses a `linguist-lock.json` file to track the state of the upstream `linguist.yml`.
 
-- When you or CI/CD run `npm run generate`, it downloads the latest data and calculates a hash.
+- When the 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.

package/dist/index.d.mts

@@ -10,24 +10,24 @@ interface Language {
      * The pretty display name of the language (e.g., "C++", "JavaScript", "JSON").
      * Use this for UI labels.
      */
-    name: string;
+    readonly name: string;
     /**
      * The category of the language.
      */
-    type: LanguageType;
+    readonly type: LanguageType;
     /**
      * List of file extensions associated with this language (e.g., [".js", ".mjs"]).
      */
-    extensions: string[];
+    readonly extensions: string[];
     /**
      * List of specific filenames associated with this language (e.g., ["Jenkinsfile"]).
      */
-    filenames: string[];
+    readonly 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;
+    readonly group?: string;
 }
 
 /**
@@ -51,29 +51,29 @@ interface Language {
 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.
+ * Returns an array of language names (strings).
  *
  * @param {LanguageType} type - The category: 'programming' | 'data' | 'markup' | 'prose'
- * @returns {Language[]} Array of Language objects matching the type, or empty array if none found
+ * @returns {string[]} Array of language names matching the type, or empty array if none found
  *
  * @example
  * const programmingLangs = getLanguagesByType('programming');
- * // => [{ name: 'JavaScript', type: 'programming', ... }, { name: 'Python', ... }, ...]
+ * // => ['JavaScript', 'Python', 'TypeScript', 'Rust', ...]
  *
  * @example
  * const dataLangs = getLanguagesByType('data');
- * // => [{ name: 'JSON', type: 'data', ... }, { name: 'YAML', ... }, ...]
+ * // => ['JSON', 'YAML', 'CSV', ...]
  *
  * @example
  * const markupLangs = getLanguagesByType('markup');
- * // => [{ name: 'HTML', type: 'markup', ... }, { name: 'XML', ... }, ...]
+ * // => ['HTML', 'XML', 'Markdown', ...]
  *
  * @example
  * // @ts-ignore - invalid type
  * const invalid = getLanguagesByType('invalid');
  * // => []
  */
-declare function getLanguagesByType(type: LanguageType): Language[];
+declare function getLanguagesByType(type: LanguageType): string[];
 /**
  * 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).

package/dist/index.d.ts

@@ -10,24 +10,24 @@ interface Language {
      * The pretty display name of the language (e.g., "C++", "JavaScript", "JSON").
      * Use this for UI labels.
      */
-    name: string;
+    readonly name: string;
     /**
      * The category of the language.
      */
-    type: LanguageType;
+    readonly type: LanguageType;
     /**
      * List of file extensions associated with this language (e.g., [".js", ".mjs"]).
      */
-    extensions: string[];
+    readonly extensions: string[];
     /**
      * List of specific filenames associated with this language (e.g., ["Jenkinsfile"]).
      */
-    filenames: string[];
+    readonly 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;
+    readonly group?: string;
 }
 
 /**
@@ -51,29 +51,29 @@ interface Language {
 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.
+ * Returns an array of language names (strings).
  *
  * @param {LanguageType} type - The category: 'programming' | 'data' | 'markup' | 'prose'
- * @returns {Language[]} Array of Language objects matching the type, or empty array if none found
+ * @returns {string[]} Array of language names matching the type, or empty array if none found
  *
  * @example
  * const programmingLangs = getLanguagesByType('programming');
- * // => [{ name: 'JavaScript', type: 'programming', ... }, { name: 'Python', ... }, ...]
+ * // => ['JavaScript', 'Python', 'TypeScript', 'Rust', ...]
  *
  * @example
  * const dataLangs = getLanguagesByType('data');
- * // => [{ name: 'JSON', type: 'data', ... }, { name: 'YAML', ... }, ...]
+ * // => ['JSON', 'YAML', 'CSV', ...]
  *
  * @example
  * const markupLangs = getLanguagesByType('markup');
- * // => [{ name: 'HTML', type: 'markup', ... }, { name: 'XML', ... }, ...]
+ * // => ['HTML', 'XML', 'Markdown', ...]
  *
  * @example
  * // @ts-ignore - invalid type
  * const invalid = getLanguagesByType('invalid');
  * // => []
  */
-declare function getLanguagesByType(type: LanguageType): Language[];
+declare function getLanguagesByType(type: LanguageType): string[];
 /**
  * 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).