tamil-toolkit 0.1.0-alpha.6 → 0.1.0-alpha.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,69 +1,184 @@
1
1
  <div align="center">
2
2
 
3
- # tamil-toolkit for JavaScript and TypeScript
3
+ # tamil-toolkit for JavaScript & TypeScript
4
4
 
5
- **Rust-backed Tamil text tools for Node.js and browsers.**
5
+ ### High-Performance Tamil Text Processing, Unicode & Font Transcoder for Node.js and Browsers
6
6
 
7
- [![npm alpha version](https://img.shields.io/npm/v/tamil-toolkit/alpha?style=flat-square&label=npm%20alpha)](https://www.npmjs.com/package/tamil-toolkit)
8
- [![Monthly downloads](https://img.shields.io/npm/dm/tamil-toolkit?style=flat-square&label=monthly)](https://www.npmjs.com/package/tamil-toolkit)
7
+ **Zero-dependency WebAssembly · Bamini / TSCII / TAB / TAM / Vanavil font conversion · Grapheme segmentation · Agara varisai sorting · Currency & Numerals · 100% offline & private**
8
+
9
+ [![npm alpha version](https://img.shields.io/npm/v/tamil-toolkit/alpha?style=flat-square&logo=npm&label=npm%20alpha)](https://www.npmjs.com/package/tamil-toolkit)
10
+ [![npm monthly downloads](https://img.shields.io/npm/dm/tamil-toolkit?style=flat-square&label=monthly)](https://www.npmjs.com/package/tamil-toolkit)
9
11
  [![CI](https://img.shields.io/github/actions/workflow/status/abishtakan/tamil-toolkit/ci.yml?branch=master&style=flat-square&label=CI)](https://github.com/abishtakan/tamil-toolkit/actions/workflows/ci.yml)
10
12
  [![MIT license](https://img.shields.io/github/license/abishtakan/tamil-toolkit?style=flat-square)](https://github.com/abishtakan/tamil-toolkit/blob/master/LICENSE)
13
+ [![TypeScript types](https://img.shields.io/badge/types-included-blue?style=flat-square&logo=typescript)](bindings/js-wasm)
14
+ [![WebAssembly](https://img.shields.io/badge/WASM-100%25%20offline-blueviolet?style=flat-square&logo=webassembly)](bindings/js-wasm)
11
15
 
12
- [Install](#install) · [Node quick start](#node-quick-start) · [Documentation](#documentation)
16
+ [Install](#install) · [Node Quick Start](#node-quick-start) · [Browser Quick Start](#browser-quick-start) · [Use Cases](#practical-web-recipes) · [Documentation](#documentation) · [License](#license)
13
17
 
14
18
  </div>
15
19
 
16
- ## What’s included
20
+ ---
21
+
22
+ **tamil-toolkit** is the premier, high-performance Tamil text and Unicode processing library for JavaScript, TypeScript, Node.js, and modern web browsers. Powered by compiled Rust WebAssembly (WASM), it brings zero-latency, deterministic Tamil computing to frontend web apps, serverless functions, and backend services.
23
+
24
+ Runs **100% client-side** with zero network tracking, zero external dependencies, and complete offline PWA compatibility.
17
25
 
18
- | Area | Capabilities |
19
- | --- | --- |
20
- | **Unicode and letters** | NFC/NFD normalization, tailored Tamil letter operations, and inspection. |
21
- | **Ordering** | Stable Mei-first Agara collation and versioned sort/search keys. |
22
- | **Numbers and dates** | Bounded TN/SL number words, exact INR/LKR amounts, fractions, and Gregorian dates. |
23
- | **Tamil calendar** | Unreleased bounded Thirukanitham Gregorian/solar conversion and five-limb panchangam reports for declared TN/SL coordinates in 2024–2027. Its custom profile does not claim every publisher's Drik output; calendar fixtures remain planned. |
24
- | **Legacy conversion** | Bamini text conversion, bounded TSCII/TAB/TAM/Anjal byte profiles, and LT-TM / IndoWord 16-bit CID conversion. |
26
+ ---
25
27
 
26
- TypeScript and WASM are thin bindings to the shared Rust implementation.
28
+ ## What is Included
29
+
30
+ | Domain | Capabilities in JS / TS / WASM |
31
+ |---|---|
32
+ | 🔤 **Unicode & Letters** | NFC/NFD normalization, tailored Tamil grapheme segmentation (`get_letters`), Mei/Uyir splitting, and scalar inspection. Handles complex ligatures like `க்ஷ` and `ஸ்ரீ`. |
33
+ | 🔄 **Legacy Font Transcoder** | Universal bidirectional transcoding between Unicode and legacy Tamil encoding formats: **Bamini**, **TSCII**, **TAB**, **TAM**, **Anjal**, **Vanavil Avvaiyar**, and **LT-TM / IndoWord**. |
34
+ | 🔠 **Agara Varisai Collation** | Traditional Tamil dictionary alphabetical sorting with stable Mei-first collation order (`sort_words`, `compare`). |
35
+ | 🔢 **Numerals & Currency** | Bounded Tamil Nadu (`ta-IN`) and Sri Lankan (`ta-LK`) number-to-words conversion, exact financial currency formatting (INR/LKR) with zero floating-point drift, and Gregorian civil dates. |
36
+ | 🎵 **Phonology & Prosody** | Tholkappiyam-grounded phonology: mora (*Maathirai*) duration calculation, letter quantity classification (`is_kuril`, `is_nedil`, `is_mei`, `is_aytham`), stop-nasal cognates (*Ina Ezhuthu*), and syllable nuclei (*Olippasai*). |
37
+ | 📅 **Solar Calendar & Panchangam** | Classical Thirukanitham Drik and 1962 Vākyakaraṇa calendar models: Gregorian ↔ Tamil solar date conversion, 60-year Jovian cycles, and five-limb astronomical panchangam calculations. |
38
+
39
+ ---
27
40
 
28
41
  ## Install
29
42
 
30
- Node.js 22+ is supported. Install alpha 6 from npm’s `alpha` dist-tag:
43
+ Node.js 22+ is supported. Install alpha 7 from npm’s `alpha` dist-tag:
31
44
 
32
45
  ```sh
33
46
  npm install tamil-toolkit@alpha
34
47
  ```
35
48
 
36
- The `alpha` tag points to `0.1.0-alpha.6`; npm’s `latest` tag still points to
37
- `0.1.0-alpha.1`. The version badge above tracks the `alpha` tag.
49
+ Or using pnpm / yarn:
38
50
 
39
- ## Node quick start
51
+ ```sh
52
+ pnpm add tamil-toolkit@alpha
53
+ # or
54
+ yarn add tamil-toolkit@alpha
55
+ ```
40
56
 
41
- ```javascript
57
+ The `alpha` tag points to `0.1.0-alpha.7`; npm’s `latest` tag still points to `0.1.0-alpha.1`. The version badge above tracks the `alpha` tag.
58
+
59
+ ---
60
+
61
+ ## Node Quick Start
62
+
63
+ In Node.js (ESM or TypeScript), the native WebAssembly module initializes automatically on import:
64
+
65
+ ```typescript
42
66
  import * as tamil from "tamil-toolkit";
43
67
 
44
- const text = "தமிழ்";
45
- console.log(tamil.get_letters(text).join(" | ")); // த | மி | ழ்
46
- console.log(tamil.unicode_to_bamini(text)); // jkpo;
47
- console.log(tamil.format_currency(102550, "LKR", "SL")); // LKR 1,025.50
68
+ // 1. Grapheme Segmentation (handles ligatures accurately)
69
+ const text = "தமிழ்நாடு";
70
+ const letters = tamil.get_letters(text);
71
+ console.log("Letters:", letters); // [ 'த', 'மி', 'ழ்', 'நா', 'டு' ]
72
+
73
+ // 2. Legacy Font Conversion (Bamini, TSCII, TAB, TAM, Vanavil)
74
+ const bamini = tamil.unicode_to_bamini(text);
75
+ console.log("Bamini encoded:", bamini); // "jkpo;ehL"
76
+ console.log("Back to Unicode:", tamil.bamini_to_unicode(bamini)); // "தமிழ்நாடு"
77
+
78
+ // 3. Exact Currency & Cheque Formatting (no float errors!)
79
+ console.log(tamil.format_currency(102550, "INR", "TN")); // "INR 1,025.50"
80
+ console.log(tamil.format_currency(102550, "LKR", "SL")); // "LKR 1,025.50"
81
+
82
+ // 4. Tamil Alphabetical Sorting (Agara Varisai)
83
+ const words = ["ஆப்பிள்", "அணில்", "இலை", "ஈட்டி"];
84
+ console.log(tamil.sort_words(words)); // [ 'அணில்', 'ஆப்பிள்', 'இலை', 'ஈட்டி' ]
48
85
  ```
49
86
 
50
- ## Browser quick start
87
+ ---
51
88
 
52
- Use the `/web` entry point and initialize WebAssembly before calling the API:
89
+ ## Browser Quick Start
53
90
 
54
- ```javascript
55
- import { init, get_letters } from "tamil-toolkit/web";
91
+ For browser applications (Vite, Next.js, Webpack, Nuxt, or Vanilla JS), use the `/web` entry point and initialize WebAssembly once before calling API methods:
56
92
 
93
+ ```typescript
94
+ import { init, get_letters, unicode_to_bamini, bamini_to_unicode } from "tamil-toolkit/web";
95
+
96
+ // 1. Initialize WebAssembly module (load and compile WASM)
57
97
  await init();
58
- console.log(get_letters("தமிழ்").join(" | "));
98
+
99
+ // 2. Ready to use!
100
+ const letters = get_letters("வணக்கம்");
101
+ console.log(letters); // [ 'வ', 'ண', 'க்', 'க', 'ம்' ]
102
+
103
+ const bamini = unicode_to_bamini("வணக்கம்");
104
+ console.log(bamini); // "tzf;fk;"
105
+ ```
106
+
107
+ ### Next.js & React Example:
108
+
109
+ ```tsx
110
+ "use client";
111
+
112
+ import { useEffect, useState } from "react";
113
+ import { init, unicode_to_bamini, bamini_to_unicode } from "tamil-toolkit/web";
114
+
115
+ export default function TamilConverter() {
116
+ const [ready, setReady] = useState(false);
117
+ const [input, setInput] = useState("தமிழ்");
118
+ const [output, setOutput] = useState("");
119
+
120
+ useEffect(() => {
121
+ init().then(() => setReady(true));
122
+ }, []);
123
+
124
+ const handleConvert = () => {
125
+ if (ready) {
126
+ setOutput(unicode_to_bamini(input));
127
+ }
128
+ };
129
+
130
+ return (
131
+ <div>
132
+ <input value={input} onChange={(e) => setInput(e.target.value)} />
133
+ <button onClick={handleConvert} disabled={!ready}>Convert to Bamini</button>
134
+ <p>Result: {output}</p>
135
+ </div>
136
+ );
137
+ }
59
138
  ```
60
139
 
61
- The host page or bundler must serve the packaged WASM asset as an ES module
62
- asset. The Node entry point initializes its native WASM module automatically.
140
+ ---
63
141
 
64
- ## Alpha 6 scope
142
+ ## Practical Web Recipes
65
143
 
66
- The npm `0.1.0-alpha.6` package includes the capabilities listed above. The
144
+ ### 1. Sorting Tamil Arrays in UI State (Agara Varisai)
145
+
146
+ Use `compare` directly in standard JavaScript `Array.prototype.sort()`:
147
+
148
+ ```typescript
149
+ import { compare } from "tamil-toolkit";
150
+
151
+ const users = [
152
+ { name: "கவிதா" },
153
+ { name: "அமுதா" },
154
+ { name: "பாரதி" }
155
+ ];
156
+
157
+ users.sort((a, b) => compare(a.name, b.name));
158
+ // Result: அமுதா, கவிதா, பாரதி
159
+ ```
160
+
161
+ ### 2. Converting Legacy Files & Clipboard Content
162
+
163
+ ```typescript
164
+ import * as tamil from "tamil-toolkit";
165
+
166
+ // Transcode Bamini clipboard text
167
+ function convertClipboard(pastedText: string): string {
168
+ try {
169
+ return tamil.bamini_to_unicode(pastedText);
170
+ } catch (err) {
171
+ console.error("Transcoding error:", err);
172
+ return pastedText;
173
+ }
174
+ }
175
+ ```
176
+
177
+ ---
178
+
179
+ ## Alpha 7 scope
180
+
181
+ The npm `0.1.0-alpha.7` package includes the capabilities listed above. The
67
182
  shared `execute` API exposes `lt_tm_codes_to_unicode`, `lt_tm_text_to_unicode`,
68
183
  `unicode_to_lt_tm_codes`, and `unicode_to_lt_tm_text`. LT-TM conversion handles
69
184
  selected 16-bit code sequences; it does not parse PDFs, select font runs, or
@@ -80,6 +195,14 @@ const codes = tamil.execute({ op: "unicode_to_lt_tm_codes", input: { text: "த
80
195
  const text = tamil.execute({ op: "lt_tm_codes_to_unicode", input: { codes } });
81
196
  ```
82
197
 
198
+ ---
199
+
200
+ ## Author & Maintainer
201
+
202
+ **Abishtakan Sivachandrathevan** ([@abishtakan](https://github.com/abishtakan))
203
+
204
+ ---
205
+
83
206
  ## Documentation
84
207
 
85
208
  - [API and feature overview](https://github.com/abishtakan/tamil-toolkit#capability-contracts)
@@ -87,12 +210,20 @@ const text = tamil.execute({ op: "lt_tm_codes_to_unicode", input: { codes } });
87
210
  - [Unicode/core contract](https://github.com/abishtakan/tamil-toolkit/blob/master/docs/specs/core-v0.1.md)
88
211
  - [Collation contract](https://github.com/abishtakan/tamil-toolkit/blob/master/docs/specs/collate-v0.1.md)
89
212
  - [Numerals, fractions, and dates](https://github.com/abishtakan/tamil-toolkit/blob/master/docs/specs/numerals-v0.2.md)
90
- - [Codec contract and alpha 3 limits](https://github.com/abishtakan/tamil-toolkit/blob/master/docs/releases/alpha-6.md#compatibility-and-scope)
213
+ - [Codec contract and alpha 3 limits](https://github.com/abishtakan/tamil-toolkit/blob/master/docs/releases/alpha-7.md#compatibility-and-scope)
91
214
  - [LT-TM CID profile contract](https://github.com/abishtakan/tamil-toolkit/blob/master/docs/specs/codec-lt-tm.md)
92
215
  - [Third-party notices](https://github.com/abishtakan/tamil-toolkit/blob/master/THIRD_PARTY_NOTICES.md)
93
216
 
217
+ ---
218
+
94
219
  ## License
95
220
 
96
221
  Original code is [MIT licensed](https://github.com/abishtakan/tamil-toolkit/blob/master/LICENSE).
97
222
  Bundled data and mappings retain their recorded terms in the
98
223
  [third-party notices](https://github.com/abishtakan/tamil-toolkit/blob/master/THIRD_PARTY_NOTICES.md).
224
+
225
+ ---
226
+
227
+ ## Keywords & Search Queries
228
+
229
+ `tamil npm`, `tamil unicode javascript`, `bamini to unicode converter npm`, `tscii to unicode javascript`, `tamil font converter web`, `tamil text processing nodejs`, `tamil sort agara varisai js`, `tamil numbers to words npm`, `tamil wasm webassembly`, `offline tamil converter`.