@mahmoud_magdy_mahmoud/smart-word-generator 1.1.1

package/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <!-- <img src="./logo.png"> -->
+  <!-- Logo generation is temporarily unavailable. Place your logo here. -->
+</p>
+<h1 align="center">Smart Word Generator</h1>
+<p align="center"><b>A TypeScript library for generating words using artificial intelligence depending on your needs.</b></p>
+  
+## Description
+
+Smart word generator is a library for generating words using artificial intelligence via the [Datamuse API](https://www.datamuse.com/api/). It allows you to find words with similar meanings, sounds, spellings, and various other relationships.
+
+Now fully rewritten in **TypeScript** for better developer experience and type safety!
+
+## Features
+
+* **Type-Safe**: Written in TypeScript with full type definitions.
+* **Unified API**: All functions accept a consistent options object.
+* **Rich Relationships**: Generate synonyms, antonyms, rhymes, and more.
+* **Flexible Filtering**: distinct parts of speech, topics, and patterns.
+
+## Installation
+
+```bash
+npm install smart-word-generator
+```
+
+## Usage
+
+Import the functions you need from the package:
+
+```typescript
+import { 
+  generateWordMeansLike, 
+  generateRhyme, 
+  generateSynonym,
+  generateAntonym,
+  generateWordSoundsLike
+} from "smart-word-generator";
+```
+
+### Options Object
+
+All generator functions accept an optional `options` object:
+
+```typescript
+interface GeneratorOptions {
+  transformToArray?: boolean;   // Return string[] if true, else detailed object[]
+  partOfSpeech?: 'n' | 'v' | 'adj' | 'adv';
+  topics?: string;              // Context topics
+  startWith?: string;           // Filter words starting with...
+  endWith?: string;             // Filter words ending with...
+  max?: number;                 // Max results
+}
+```
+
+### Examples
+
+#### Find words with similar meaning
+```typescript
+const words = await generateWordMeansLike("great", { 
+  partOfSpeech: "adj", 
+  transformToArray: true,
+  max: 5
+});
+console.log(words); 
+// Output: ['big', 'huge', 'vast', 'large', 'grand']
+```
+
+#### Find Rhymes
+```typescript
+const rhymes = await generateRhyme("cat", { max: 5, transformToArray: true });
+console.log(rhymes);
+// Output: ['hat', 'bat', 'rat', 'mat', 'fat']
+```
+
+#### Find Synonyms
+```typescript
+await generateSynonym("happy");
+```
+
+#### Find Antonyms
+```typescript
+await generateAntonym("hot");
+```
+
+#### Find Words Sounding Like
+```typescript
+await generateWordSoundsLike("flower");
+```
+
+#### Find Adjectives describing a Noun
+```typescript
+// Find adjectives often used to describe 'ocean'
+await generateAdjectiveForNoun("ocean");
+```
+
+#### Find Nouns described by an Adjective
+```typescript
+// Find nouns often described as 'blue'
+await generateNounForAdjective("blue");
+```
+
+## API List
+
+* `generateWordMeansLike(word, options)`
+* `generateWordSoundsLike(word, options)`
+* `generateWordSpelledLike(word, options)`
+* `generateRhyme(word, options)`
+* `generateSynonym(word, options)`
+* `generateAntonym(word, options)`
+* `generateAdjectiveForNoun(word, options)`
+* `generateNounForAdjective(word, options)`
+* `generateWordHasLeftContext(word, options)`
+* `generateWordHasRightContext(word, options)`
+* `generateRelatedWord(word, relationCode, options)`
+
+## License
+ISC

package/dist/generators/index.d.ts

@@ -0,0 +1,48 @@
+import { GeneratorOptions, DatamuseWord } from "../utils";
+/**
+ * Generate words that have similar meaning to the input word.
+ */
+export declare const generateWordMeansLike: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate words that sound like the input word.
+ */
+export declare const generateWordSoundsLike: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate words that are spelled like the input word.
+ */
+export declare const generateWordSpelledLike: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate words that appear immediately to the left of the target word in a sentence.
+ * (Frequent predecessors)
+ */
+export declare const generateWordHasLeftContext: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate words that appear immediately to the right of the target word in a sentence.
+ * (Frequent followers)
+ */
+export declare const generateWordHasRightContext: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate synonyms for the input word.
+ */
+export declare const generateSynonym: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate antonyms for the input word.
+ */
+export declare const generateAntonym: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate rhymes for the input word.
+ */
+export declare const generateRhyme: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate adjectives that are often used to describe the given noun.
+ */
+export declare const generateAdjectiveForNoun: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate nouns that are often described by the given adjective.
+ */
+export declare const generateNounForAdjective: (word: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;
+/**
+ * Generate related words using a specific relation code.
+ * @param relationCode The Datamuse relation code (e.g., 'rel_trg', 'rel_gen').
+ */
+export declare const generateRelatedWord: (word: string, relationCode: string, options?: GeneratorOptions) => Promise<string[] | DatamuseWord[]>;

package/dist/generators/index.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRelatedWord = exports.generateNounForAdjective = exports.generateAdjectiveForNoun = exports.generateRhyme = exports.generateAntonym = exports.generateSynonym = exports.generateWordHasRightContext = exports.generateWordHasLeftContext = exports.generateWordSpelledLike = exports.generateWordSoundsLike = exports.generateWordMeansLike = void 0;
+const axios_1 = __importDefault(require("axios"));
+const utils_1 = require("../utils");
+/**
+ * Base function to generate words from Datamuse API.
+ * @param queryParam The primary query parameter (e.g., 'ml', 'sl', 'sp', 'rel_syn').
+ * @param word The input word.
+ * @param options Generator options.
+ */
+const generateWords = async (queryParam, word, options = {}) => {
+    try {
+        const optionalParams = (0, utils_1.wordOptionalParams)(options);
+        const url = `https://api.datamuse.com/words?${queryParam}=${encodeURIComponent(word)}&${optionalParams}`;
+        // Use generic type for axios response
+        const response = await axios_1.default.get(url);
+        return (0, utils_1.decorateWords)(response, options);
+    }
+    catch (err) {
+        console.error(`Error generating words for ${queryParam}=${word}:`, err);
+        return [];
+    }
+};
+/**
+ * Generate words that have similar meaning to the input word.
+ */
+const generateWordMeansLike = (word, options) => {
+    return generateWords("ml", word, options);
+};
+exports.generateWordMeansLike = generateWordMeansLike;
+/**
+ * Generate words that sound like the input word.
+ */
+const generateWordSoundsLike = (word, options) => {
+    return generateWords("sl", word, options);
+};
+exports.generateWordSoundsLike = generateWordSoundsLike;
+/**
+ * Generate words that are spelled like the input word.
+ */
+const generateWordSpelledLike = (word, options) => {
+    return generateWords("sp", word, options);
+};
+exports.generateWordSpelledLike = generateWordSpelledLike;
+/**
+ * Generate words that appear immediately to the left of the target word in a sentence.
+ * (Frequent predecessors)
+ */
+const generateWordHasLeftContext = (word, options) => {
+    // 'lc' is the legacy parameter for left context, equivalent to rel_bgb? 
+    // API docs say 'lc' is "Left Context". 
+    // We will stick to 'lc' as in original code unless we want to switch to 'rel_bgb'.
+    // Let's stick to 'lc' to match exact behavior, but documented as such.
+    return generateWords("lc", word, options);
+};
+exports.generateWordHasLeftContext = generateWordHasLeftContext;
+/**
+ * Generate words that appear immediately to the right of the target word in a sentence.
+ * (Frequent followers)
+ */
+const generateWordHasRightContext = (word, options) => {
+    return generateWords("rc", word, options);
+};
+exports.generateWordHasRightContext = generateWordHasRightContext;
+/**
+ * Generate synonyms for the input word.
+ */
+const generateSynonym = (word, options) => {
+    return generateWords("rel_syn", word, options);
+};
+exports.generateSynonym = generateSynonym;
+/**
+ * Generate antonyms for the input word.
+ */
+const generateAntonym = (word, options) => {
+    return generateWords("rel_ant", word, options);
+};
+exports.generateAntonym = generateAntonym;
+/**
+ * Generate rhymes for the input word.
+ */
+const generateRhyme = (word, options) => {
+    return generateWords("rel_rhy", word, options);
+};
+exports.generateRhyme = generateRhyme;
+/**
+ * Generate adjectives that are often used to describe the given noun.
+ */
+const generateAdjectiveForNoun = (word, options) => {
+    return generateWords("rel_jjb", word, options);
+};
+exports.generateAdjectiveForNoun = generateAdjectiveForNoun;
+/**
+ * Generate nouns that are often described by the given adjective.
+ */
+const generateNounForAdjective = (word, options) => {
+    return generateWords("rel_jja", word, options);
+};
+exports.generateNounForAdjective = generateNounForAdjective;
+/**
+ * Generate related words using a specific relation code.
+ * @param relationCode The Datamuse relation code (e.g., 'rel_trg', 'rel_gen').
+ */
+const generateRelatedWord = (word, relationCode, options) => {
+    return generateWords(relationCode, word, options);
+};
+exports.generateRelatedWord = generateRelatedWord;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./generators";
+export * from "./utils";

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./generators"), exports);
+__exportStar(require("./utils"), exports); // Verify if utils should be exported. Original didn't, but exporting types is good.
+// Original index.js only exported generators.
+// "I want to make the full project in TS... also if you can create better logo..."
+// "Also enhance and refactor current code"
+// Exporting types is essential for TS users.

package/dist/utils/index.d.ts

@@ -0,0 +1,37 @@
+import { AxiosResponse } from 'axios';
+export interface DatamuseWord {
+    word: string;
+    score: number;
+    tags?: string[];
+    defs?: string[];
+    numSyllables?: number;
+}
+export interface GeneratorOptions {
+    /**
+     * If true, return an array of strings (words) instead of an array of objects.
+     * @default false
+     */
+    transformToArray?: boolean;
+    /**
+     * Filter result by part-of-speech: 'n' (noun), 'v' (verb), 'adj' (adjective), 'adv' (adverb).
+     */
+    partOfSpeech?: 'n' | 'v' | 'adj' | 'adv';
+    /**
+     * Topic words to influence the result.
+     */
+    topics?: string;
+    /**
+     * Filter results to words starting with this string/character.
+     */
+    startWith?: string;
+    /**
+     * Filter results to words ending with this string/character.
+     */
+    endWith?: string;
+    /**
+     * Maximum number of results to return.
+     */
+    max?: number;
+}
+export declare const wordOptionalParams: (options: GeneratorOptions) => string;
+export declare const decorateWords: (response: AxiosResponse<DatamuseWord[]>, options: GeneratorOptions) => DatamuseWord[] | string[];

package/dist/utils/index.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decorateWords = exports.wordOptionalParams = void 0;
+const wordOptionalParams = (options) => {
+    const { topics, startWith, endWith, max } = options;
+    const params = [];
+    if (topics) {
+        params.push(`topics=${encodeURIComponent(topics)}`);
+    }
+    if (max) {
+        params.push(`max=${max}`);
+    }
+    const start = startWith || "";
+    const end = endWith || "";
+    // 'sp' stands for spelled like. Wildcards * are used.
+    params.push(`sp=${start}*${end}`);
+    // 'md=p' requests part-of-speech tags
+    params.push("md=p");
+    return params.join('&');
+};
+exports.wordOptionalParams = wordOptionalParams;
+const filterWords = (words, type) => {
+    return words.filter((word) => {
+        return word.tags && word.tags.includes(type);
+    });
+};
+const arrayOfWordsTransformer = (words) => {
+    return words.map((w) => w.word);
+};
+const decorateWords = (response, options) => {
+    // Extract data safely
+    let words = response.data || [];
+    // Filter by part of speech if requested
+    if (options.partOfSpeech) {
+        words = filterWords(words, options.partOfSpeech);
+    }
+    // Transform to simple array if requested
+    if (options.transformToArray) {
+        return arrayOfWordsTransformer(words);
+    }
+    return words;
+};
+exports.decorateWords = decorateWords;

package/generators/index.ts

@@ -0,0 +1,111 @@
+import axios from "axios";
+import { wordOptionalParams, decorateWords, GeneratorOptions, DatamuseWord } from "../utils";
+
+/**
+ * Base function to generate words from Datamuse API.
+ * @param queryParam The primary query parameter (e.g., 'ml', 'sl', 'sp', 'rel_syn').
+ * @param word The input word.
+ * @param options Generator options.
+ */
+const generateWords = async (
+    queryParam: string,
+    word: string,
+    options: GeneratorOptions = {}
+): Promise<DatamuseWord[] | string[]> => {
+    try {
+        const optionalParams = wordOptionalParams(options);
+        const url = `https://api.datamuse.com/words?${queryParam}=${encodeURIComponent(word)}&${optionalParams}`;
+
+        // Use generic type for axios response
+        const response = await axios.get<DatamuseWord[]>(url);
+
+        return decorateWords(response, options);
+    } catch (err) {
+        console.error(`Error generating words for ${queryParam}=${word}:`, err);
+        return [];
+    }
+};
+
+/**
+ * Generate words that have similar meaning to the input word.
+ */
+export const generateWordMeansLike = (word: string, options?: GeneratorOptions) => {
+    return generateWords("ml", word, options);
+};
+
+/**
+ * Generate words that sound like the input word.
+ */
+export const generateWordSoundsLike = (word: string, options?: GeneratorOptions) => {
+    return generateWords("sl", word, options);
+};
+
+/**
+ * Generate words that are spelled like the input word.
+ */
+export const generateWordSpelledLike = (word: string, options?: GeneratorOptions) => {
+    return generateWords("sp", word, options);
+};
+
+/**
+ * Generate words that appear immediately to the left of the target word in a sentence.
+ * (Frequent predecessors)
+ */
+export const generateWordHasLeftContext = (word: string, options?: GeneratorOptions) => {
+    // 'lc' is the legacy parameter for left context, equivalent to rel_bgb? 
+    // API docs say 'lc' is "Left Context". 
+    // We will stick to 'lc' as in original code unless we want to switch to 'rel_bgb'.
+    // Let's stick to 'lc' to match exact behavior, but documented as such.
+    return generateWords("lc", word, options);
+};
+
+/**
+ * Generate words that appear immediately to the right of the target word in a sentence.
+ * (Frequent followers)
+ */
+export const generateWordHasRightContext = (word: string, options?: GeneratorOptions) => {
+    return generateWords("rc", word, options);
+};
+
+/**
+ * Generate synonyms for the input word.
+ */
+export const generateSynonym = (word: string, options?: GeneratorOptions) => {
+    return generateWords("rel_syn", word, options);
+};
+
+/**
+ * Generate antonyms for the input word.
+ */
+export const generateAntonym = (word: string, options?: GeneratorOptions) => {
+    return generateWords("rel_ant", word, options);
+};
+
+/**
+ * Generate rhymes for the input word.
+ */
+export const generateRhyme = (word: string, options?: GeneratorOptions) => {
+    return generateWords("rel_rhy", word, options);
+};
+
+/**
+ * Generate adjectives that are often used to describe the given noun.
+ */
+export const generateAdjectiveForNoun = (word: string, options?: GeneratorOptions) => {
+    return generateWords("rel_jjb", word, options);
+};
+
+/**
+ * Generate nouns that are often described by the given adjective.
+ */
+export const generateNounForAdjective = (word: string, options?: GeneratorOptions) => {
+    return generateWords("rel_jja", word, options);
+};
+
+/**
+ * Generate related words using a specific relation code.
+ * @param relationCode The Datamuse relation code (e.g., 'rel_trg', 'rel_gen').
+ */
+export const generateRelatedWord = (word: string, relationCode: string, options?: GeneratorOptions) => {
+    return generateWords(relationCode, word, options);
+};

package/index.ts

@@ -0,0 +1,6 @@
+export * from "./generators";
+export * from "./utils"; // Verify if utils should be exported. Original didn't, but exporting types is good.
+// Original index.js only exported generators.
+// "I want to make the full project in TS... also if you can create better logo..."
+// "Also enhance and refactor current code"
+// Exporting types is essential for TS users.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mahmoud_magdy_mahmoud/smart-word-generator",
+  "version": "1.1.1",
+  "description": "Generate specific words using AI (Datamuse API) depending on your needs. Fully typed with TypeScript.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mahmoud-Magdy-deeplearning/smart-word-generator.git"
+  },
+  "keywords": [
+    "word",
+    "generator",
+    "AI",
+    "NLP",
+    "typescript",
+    "datamuse",
+    "synonyms",
+    "rhymes"
+  ],
+  "author": "Mahmoud Magdy",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Mahmoud-Magdy-deeplearning/smart-word-generator/issues"
+  },
+  "homepage": "https://github.com/Mahmoud-Magdy-deeplearning/smart-word-generator#readme",
+  "dependencies": {
+    "axios": "^1.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2018",
+    "module": "commonjs",
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/utils/index.ts

@@ -0,0 +1,89 @@
+import { AxiosResponse } from 'axios';
+
+export interface DatamuseWord {
+    word: string;
+    score: number;
+    tags?: string[];
+    defs?: string[];
+    numSyllables?: number;
+}
+
+export interface GeneratorOptions {
+    /**
+     * If true, return an array of strings (words) instead of an array of objects.
+     * @default false
+     */
+    transformToArray?: boolean;
+    /**
+     * Filter result by part-of-speech: 'n' (noun), 'v' (verb), 'adj' (adjective), 'adv' (adverb).
+     */
+    partOfSpeech?: 'n' | 'v' | 'adj' | 'adv';
+    /**
+     * Topic words to influence the result.
+     */
+    topics?: string;
+    /**
+     * Filter results to words starting with this string/character.
+     */
+    startWith?: string;
+    /**
+     * Filter results to words ending with this string/character.
+     */
+    endWith?: string;
+    /**
+     * Maximum number of results to return.
+     */
+    max?: number;
+}
+
+export const wordOptionalParams = (options: GeneratorOptions): string => {
+    const { topics, startWith, endWith, max } = options;
+    const params: string[] = [];
+
+    if (topics) {
+        params.push(`topics=${encodeURIComponent(topics)}`);
+    }
+    if (max) {
+        params.push(`max=${max}`);
+    }
+
+    const start = startWith || "";
+    const end = endWith || "";
+    // 'sp' stands for spelled like. Wildcards * are used.
+    params.push(`sp=${start}*${end}`);
+
+    // 'md=p' requests part-of-speech tags
+    params.push("md=p");
+
+    return params.join('&');
+};
+
+const filterWords = (words: DatamuseWord[], type: string): DatamuseWord[] => {
+    return words.filter((word) => {
+        return word.tags && word.tags.includes(type);
+    });
+};
+
+const arrayOfWordsTransformer = (words: DatamuseWord[]): string[] => {
+    return words.map((w) => w.word);
+};
+
+export const decorateWords = (
+    response: AxiosResponse<DatamuseWord[]>,
+    options: GeneratorOptions
+): DatamuseWord[] | string[] => {
+    // Extract data safely
+    let words = response.data || [];
+
+    // Filter by part of speech if requested
+    if (options.partOfSpeech) {
+        words = filterWords(words, options.partOfSpeech);
+    }
+
+    // Transform to simple array if requested
+    if (options.transformToArray) {
+        return arrayOfWordsTransformer(words);
+    }
+
+    return words;
+};