zodiac-mapper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fixicelo
+
+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,80 @@
+# zodiac-mapper
+A lightweight, zero-dependency TypeScript NPM package that maps **zodiac sign names in dozens of languages and regional variants** to a standardized `ZodiacSign` enum.
+
+Perfect for internationalized astrology apps, horoscope tools, multilingual chatbots, or any project needing robust zodiac name recognition.
+
+Supports **50+ locales** including English, Chinese, Japanese, German, French, Spanish, Arabic, Persian, Russian, Greek, Hebrew, and more.
+
+Data note: the built-in locale alias dataset was generated and curated with AI assistance. While we try to keep it accurate and conventional, it may contain mistakes or regional variations—please open an issue/PR if you spot a problem.
+
+## Features
+
+- Map any language variant → standard zodiac enum
+- Case-insensitive, accent-insensitive, and whitespace-tolerant matching
+- Find the first or all zodiac mentions in a text string
+- No external dependencies
+- Fully typed with TypeScript
+
+## Usage
+
+```ts
+import {
+  createZodiacMatcher,
+  findAllZodiacInText,
+  findFirstZodiacInText,
+  getZodiacDateRange,
+  getZodiacSign,
+  getZodiacSignFromDate,
+  getSupportedLocales,
+  ZodiacSign,
+} from "zodiac-mapper";
+
+// 1) Map a single name to a ZodiacSign (or null if unknown)
+getZodiacSign("Taureau") === ZodiacSign.TAURUS;
+getZodiacSign("Unknown") === null;
+
+// 2) Scan text: find the first match (or null if none)
+const first = findFirstZodiacInText("My sign is Löwe");
+// first => { sign: ZodiacSign.LEO, match: "Löwe", index: 11 }
+
+// 3) Scan text: find all matches (empty array if none)
+const all = findAllZodiacInText("Aries, Taurus, and Löwe");
+// all => [
+//   { sign: ZodiacSign.ARIES, match: "Aries", index: 0 },
+//   { sign: ZodiacSign.TAURUS, match: "Taurus", index: 7 },
+//   { sign: ZodiacSign.LEO, match: "Löwe", index: 19 },
+// ]
+
+// Inspect available locale data keys
+const locales = getSupportedLocales();
+// locales => ["en", "fr", "de", ...]
+
+// 4) Reuse a matcher with fixed options (saves repeated option passing)
+const ptOnly = createZodiacMatcher({ includeLocales: ["pt"] });
+ptOnly.getZodiacSign("Áries") === ZodiacSign.ARIES;
+
+// 5) Date helpers (tropical / Western zodiac)
+getZodiacDateRange(ZodiacSign.ARIES);
+// => { start: { month: 3, day: 21 }, end: { month: 4, day: 19 }, crossesYear: false }
+
+getZodiacSignFromDate({ month: 3, day: 21 }) === ZodiacSign.ARIES;
+getZodiacSignFromDate("2000-03-21") === ZodiacSign.ARIES;
+getZodiacSignFromDate("03-21") === ZodiacSign.ARIES;
+```
+
+### Locale Filtering (include / exclude)
+
+When scanning free text, limiting languages can reduce false positives.
+
+```ts
+// Only match Portuguese
+getZodiacSign("Áries", { includeLocales: ["pt"] });
+
+// Scan text but exclude Portuguese
+findFirstZodiacInText("I am Áries", { excludeLocales: ["pt"] });
+```
+
+Notes:
+- Locales are treated as BCP-47 tags; tags like `zh-Hant` will be treated as `zh` for filtering.
+- `symbols` is a special built-in pseudo-locale key (not a BCP-47 tag).
+- The default is permissive (all locales). This is great for astrology-specific text, but can be noisy in general-purpose text.