odmieniacz.js 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# odmieniacz.js
+
+Simple Polish declension (cases) API powered by [`morfeusz2-node-bindings`](https://www.npmjs.com/package/morfeusz2-node-bindings).
+
+## Usage
+
+```js
+const odm = require("odmieniacz.js");
+
+odm.dative("Marcin");   // "Marcinowi"
+odm.vocative("Marcin"); // "Marcinie"
+
+odm.accusative("Marcin"); // "Marcina"
+odm.cases("Marcin");
+```
+
+## Notes
+
+- This library is sync-only.
+- This package is **heavy** (native Morfeusz2 + dictionary) and is intended for **server-side** usage (Node.js), not the browser.
+- It inflects **single tokens** (one word at a time).
+- Under the hood it:
+  1) runs Morfeusz analysis to pick the best interpretation (`lemma` + `tag`)
+  2) rewrites the tag case (`nom/gen/dat/acc/inst/loc/voc`)
+  3) calls Morfeusz synthesis (`generateTagged`)
+
+If you need full control, you can pass `opts.lemma`/`opts.tag`, or call `analyse()` / `generateTagged()` directly.

package/index.d.ts

@@ -0,0 +1,121 @@
+export type CaseName =
+  | "nominative"
+  | "genitive"
+  | "dative"
+  | "accusative"
+  | "instrumental"
+  | "locative"
+  | "vocative"
+  | "mianownik"
+  | "dopelniacz"
+  | "dopełniacz"
+  | "celownik"
+  | "biernik"
+  | "narzednik"
+  | "narzędnik"
+  | "miejscownik"
+  | "wolacz"
+  | "wołacz";
+
+export type CaseCode = "nom" | "gen" | "dat" | "acc" | "inst" | "loc" | "voc";
+
+export interface MorfeuszVersion {
+  addon: string;
+  napi: number;
+  morfeusz?: string;
+}
+
+export interface AnalyseOpts {
+  returnGraph?: boolean;
+  keepWhitespace?: boolean;
+  caseSensitiveLemmas?: boolean;
+}
+
+export interface Interpretation {
+  lemma: string;
+  tag: string;
+  name?: string;
+}
+
+export interface AnalysisToken {
+  token: string;
+  start: number;
+  end: number;
+  interpretations: Interpretation[];
+}
+
+export interface AnalysisGraphEdge {
+  from: number;
+  to: number;
+  orth: string;
+  interp: Interpretation;
+}
+
+export interface AnalysisGraph {
+  nodes: number;
+  edges: AnalysisGraphEdge[];
+}
+
+export interface AnalysisResult {
+  tokens: AnalysisToken[];
+  graph?: AnalysisGraph;
+}
+
+export interface GenerateOpts {
+  includeTags?: boolean;
+  dedupe?: boolean;
+  returnAllByLemmaVariant?: boolean;
+}
+
+export type GenerateAllResult = string[] | Array<{ form: string; tag: string; name?: string }>;
+
+export interface DictionaryInfo {
+  embedded: boolean;
+  defaultDir?: string;
+  current?: string;
+}
+
+export interface InflectOpts {
+  lemma?: string;
+  tag?: string;
+  dedupe?: boolean;
+  all?: boolean;
+  analyseOpts?: Omit<AnalyseOpts, "returnGraph">;
+}
+
+export interface AllCases {
+  nominative: string;
+  genitive: string;
+  dative: string;
+  accusative: string;
+  instrumental: string;
+  locative: string;
+  vocative: string;
+}
+
+export function version(): MorfeuszVersion;
+export function analyse(text: string, opts?: AnalyseOpts): AnalysisResult;
+export function generate(lemma: string, opts?: GenerateOpts): GenerateAllResult;
+export function generateTagged(lemma: string, tag: string, opts?: GenerateOpts): string[];
+export function setDictionary(pathOrName: string): void;
+export function getDictionaryInfo(): DictionaryInfo;
+
+export function case(word: string, caseName: CaseName | CaseCode, opts?: InflectOpts): string | string[];
+export function cases(word: string, opts?: InflectOpts): AllCases;
+
+export function nominative(word: string, opts?: InflectOpts): string | string[];
+export function genitive(word: string, opts?: InflectOpts): string | string[];
+export function dative(word: string, opts?: InflectOpts): string | string[];
+export function accusative(word: string, opts?: InflectOpts): string | string[];
+export function instrumental(word: string, opts?: InflectOpts): string | string[];
+export function locative(word: string, opts?: InflectOpts): string | string[];
+export function vocative(word: string, opts?: InflectOpts): string | string[];
+
+export function mianownik(word: string, opts?: InflectOpts): string | string[];
+export function dopelniacz(word: string, opts?: InflectOpts): string | string[];
+export function celownik(word: string, opts?: InflectOpts): string | string[];
+export function biernik(word: string, opts?: InflectOpts): string | string[];
+export function narzednik(word: string, opts?: InflectOpts): string | string[];
+export function miejscownik(word: string, opts?: InflectOpts): string | string[];
+export function wolacz(word: string, opts?: InflectOpts): string | string[];
+

package/index.js

@@ -0,0 +1,242 @@
+"use strict";
+
+const morfeusz = require("morfeusz2-node-bindings");
+
+const CASE_CODE_BY_NAME = Object.freeze({
+  nominative: "nom",
+  genitive: "gen",
+  dative: "dat",
+  accusative: "acc",
+  instrumental: "inst",
+  locative: "loc",
+  vocative: "voc",
+
+  mianownik: "nom",
+  dopelniacz: "gen",
+  dopełniacz: "gen",
+  celownik: "dat",
+  biernik: "acc",
+  narzednik: "inst",
+  narzędnik: "inst",
+  miejscownik: "loc",
+  wolacz: "voc",
+  wołacz: "voc"
+});
+
+const CASE_CODES = new Set(["nom", "gen", "dat", "acc", "inst", "loc", "voc"]);
+const NUMBER_CODES = new Set(["sg", "pl"]);
+const GENDER_CODES = new Set([
+  "m1",
+  "m2",
+  "m3",
+  "f",
+  "n1",
+  "n2",
+  "p1",
+  "p2",
+  "p3"
+]);
+
+function assertString(value, name) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${name} must be a string`);
+  }
+}
+
+function normalizeWord(word) {
+  assertString(word, "word");
+  const trimmed = word.trim();
+  if (!trimmed) throw new TypeError("word must be a non-empty string");
+  if (/\s/.test(trimmed)) {
+    throw new TypeError(
+      "word must be a single token (no whitespace); pass one word at a time"
+    );
+  }
+  return trimmed;
+}
+
+function normalizeCase(caseName) {
+  assertString(caseName, "caseName");
+  const key = caseName.trim().toLowerCase();
+  const code = CASE_CODE_BY_NAME[key];
+  if (!code) {
+    const known = Object.keys(CASE_CODE_BY_NAME)
+      .filter((k) => !k.includes("ł") && !k.includes("ó") && !k.includes("ę"))
+      .slice(0, 7)
+      .join(", ");
+    throw new TypeError(
+      `Unknown case "${caseName}". Use: ${known} (or Polish names).`
+    );
+  }
+  return code;
+}
+
+function scoreInterpretation(interpretation) {
+  const tag = interpretation.tag || "";
+  const parts = tag.split(":");
+
+  let score = 0;
+  if (parts[0] === "subst") score += 100;
+  if (parts[0] === "depr") score += 90;
+  if (parts[0] === "adj") score += 70;
+  if (parts.includes("sg")) score += 10;
+  if (parts.includes("nom")) score += 5;
+  if (parts.includes("prop")) score += 2;
+
+  return score;
+}
+
+function extractTagFeatures(tag) {
+  const parts = String(tag || "").split(":");
+  return {
+    pos: parts[0] || "",
+    number: parts.find((p) => NUMBER_CODES.has(p)),
+    gender: parts.find((p) => GENDER_CODES.has(p))
+  };
+}
+
+function tagHasCase(tag, targetCase) {
+  const parts = String(tag || "").split(":");
+  for (const part of parts) {
+    if (part === targetCase) return true;
+    if (part.includes(".") && part.split(".").includes(targetCase)) return true;
+  }
+  return false;
+}
+
+function filterGeneratedForms(items, base, targetCase) {
+  const matchCase = items.filter((it) => tagHasCase(it.tag, targetCase));
+  if (matchCase.length < 1) return matchCase;
+
+  const withNumber = base.number
+    ? matchCase.filter((it) => String(it.tag || "").split(":").includes(base.number))
+    : matchCase;
+
+  const withPos = base.pos
+    ? withNumber.filter((it) => String(it.tag || "").split(":")[0] === base.pos)
+    : withNumber;
+
+  const withGender =
+    base.gender && withPos.length
+      ? withPos.filter((it) => String(it.tag || "").split(":").includes(base.gender))
+      : withPos;
+
+  if (withGender.length) return withGender;
+  if (withPos.length) return withPos;
+  if (withNumber.length) return withNumber;
+  return matchCase;
+}
+
+function pickBestInterpretation(word, opts) {
+  const analysis = morfeusz.analyse(word, { returnGraph: false, ...(opts || {}) });
+  if (!analysis || !Array.isArray(analysis.tokens) || analysis.tokens.length < 1) {
+    throw new Error("Morfeusz returned an empty analysis result");
+  }
+
+  const token = analysis.tokens.find((t) => t && t.token === word) || analysis.tokens[0];
+  const interpretations = (token && token.interpretations) || [];
+  if (interpretations.length < 1) {
+    throw new Error(`No interpretations for "${word}"`);
+  }
+
+  return interpretations
+    .slice()
+    .sort((a, b) => scoreInterpretation(b) - scoreInterpretation(a))[0];
+}
+
+function generateOne(word, targetCase, opts) {
+  const options = opts || {};
+  const lemma = options.lemma;
+  const tag = options.tag;
+
+  let chosenLemma = lemma;
+  let chosenTag = tag;
+
+  if (!chosenLemma || !chosenTag) {
+    const best = pickBestInterpretation(word, options.analyseOpts);
+    chosenLemma = chosenLemma || best.lemma;
+    chosenTag = chosenTag || best.tag;
+  }
+
+  const generated = morfeusz.generate(chosenLemma, {
+    includeTags: true,
+    dedupe: options.dedupe !== false,
+    returnAllByLemmaVariant: true
+  });
+
+  if (!Array.isArray(generated)) {
+    throw new Error("Morfeusz returned an invalid generate() result");
+  }
+  if (generated.length < 1) {
+    throw new Error(`No generated forms for lemma "${chosenLemma}"`);
+  }
+  if (typeof generated[0] === "string") {
+    throw new Error(
+      "Morfeusz generate() returned string forms, but tag info is required; ensure bindings support includeTags:true"
+    );
+  }
+
+  const base = extractTagFeatures(chosenTag);
+  const forms = filterGeneratedForms(generated, base, targetCase).map((it) => it.form);
+
+  if (!forms || forms.length < 1) {
+    const hint = chosenLemma === word ? "" : ` (lemma="${chosenLemma}")`;
+    throw new Error(`No generated forms for "${word}" in case "${targetCase}"${hint}`);
+  }
+
+  return options.all ? forms : forms[0];
+}
+
+function caseForm(word, caseNameOrCode, opts) {
+  const normalized = normalizeWord(word);
+  const targetCase = CASE_CODES.has(caseNameOrCode)
+    ? caseNameOrCode
+    : normalizeCase(caseNameOrCode);
+  return generateOne(normalized, targetCase, opts);
+}
+
+function allCases(word, opts) {
+  const normalized = normalizeWord(word);
+  const best = pickBestInterpretation(normalized, (opts && opts.analyseOpts) || undefined);
+  const lemma = (opts && opts.lemma) || best.lemma;
+  const tag = (opts && opts.tag) || best.tag;
+
+  const baseOpts = { ...(opts || {}), lemma, tag };
+  return {
+    nominative: generateOne(normalized, "nom", baseOpts),
+    genitive: generateOne(normalized, "gen", baseOpts),
+    dative: generateOne(normalized, "dat", baseOpts),
+    accusative: generateOne(normalized, "acc", baseOpts),
+    instrumental: generateOne(normalized, "inst", baseOpts),
+    locative: generateOne(normalized, "loc", baseOpts),
+    vocative: generateOne(normalized, "voc", baseOpts)
+  };
+}
+
+module.exports = {
+  version: morfeusz.version,
+  analyse: morfeusz.analyse,
+  generate: morfeusz.generate,
+  generateTagged: morfeusz.generateTagged,
+  setDictionary: morfeusz.setDictionary,
+  getDictionaryInfo: morfeusz.getDictionaryInfo,
+
+  case: caseForm,
+  cases: allCases,
+
+  nominative: (w, o) => caseForm(w, "nom", o),
+  genitive: (w, o) => caseForm(w, "gen", o),
+  dative: (w, o) => caseForm(w, "dat", o),
+  accusative: (w, o) => caseForm(w, "acc", o),
+  instrumental: (w, o) => caseForm(w, "inst", o),
+  locative: (w, o) => caseForm(w, "loc", o),
+  vocative: (w, o) => caseForm(w, "voc", o),
+
+  mianownik: (w, o) => caseForm(w, "nom", o),
+  dopelniacz: (w, o) => caseForm(w, "gen", o),
+  celownik: (w, o) => caseForm(w, "dat", o),
+  biernik: (w, o) => caseForm(w, "acc", o),
+  narzednik: (w, o) => caseForm(w, "inst", o),
+  miejscownik: (w, o) => caseForm(w, "loc", o),
+  wolacz: (w, o) => caseForm(w, "voc", o)
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "odmieniacz.js",
+  "version": "0.1.0",
+  "description": "Simple Polish declension (cases) API powered by Morfeusz2.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node scripts/smoke.js"
+  },
+  "dependencies": {
+    "morfeusz2-node-bindings": "^0.1.2"
+  },
+  "overrides": {
+    "tar": "7.5.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "scripts/"
+  ],
+  "keywords": [
+    "polish",
+    "morphology",
+    "declension",
+    "inflection",
+    "morfeusz",
+    "morfeusz2"
+  ],
+  "license": "MIT"
+}

package/scripts/smoke.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const odm = require("..");
+
+console.log("version()", odm.version());
+
+const dat = odm.dative("Marcin", { all: true });
+const voc = odm.vocative("Marcin", { all: true });
+const acc = odm.accusative("Marcin", { all: true });
+
+console.log("dative(Marcin)", dat);
+console.log("vocative(Marcin)", voc);
+console.log("accusative(Marcin)", acc);
+
+assert.ok(Array.isArray(dat) ? dat.includes("Marcinowi") : dat === "Marcinowi");
+assert.ok(Array.isArray(voc) ? voc.includes("Marcinie") : voc === "Marcinie");
+assert.ok(Array.isArray(acc) ? acc.includes("Marcina") : acc === "Marcina");
+
+console.log("OK");
+