[JS] Preparing the JS package for preview release (openvinotoolkit#1775)

Details:
- Code refactoring:
  - Renamed entity from `Pipeline` to `LLMpipeline`
  - Renamed JS package from `genai-node` to `openvino-genai-node`
  - Refactored import of buildings
  - Improving code style with `ESLint`
  - Updated version to `2025.1.0-preview`
- Adding post-installation binary downloads

Tickets:
- CVS-161447

---------

Signed-off-by: Kirill Suvorov <kirill.suvorov@intel.com>

Author: Retribution98

.github/workflows/linux.yml

@@ -452,11 +452,15 @@ jobs:
           rm -rf node_modules/openvino-node/bin
           cp -R ${{ env.OV_INSTALL_DIR }}/openvino_js_package node_modules/openvino-node/bin
 
+      - name: Check lint
+        working-directory: ${{ env.SRC_DIR }}/src/js
+        run: npm run lint
+
       - name: Run npm package tests
         working-directory: ${{ env.SRC_DIR }}/src/js
         run: npm test
 
-      - name: Install genai-node samples dependencies
+      - name: Install openvino-genai-node samples dependencies
         working-directory: ${{ env.SRC_DIR }}/samples/js/text_generation
         run: |
           npm install --verbose

.github/workflows/windows.yml

@@ -543,11 +543,15 @@ jobs:
           Remove-Item -Recurse -Force node_modules/openvino-node/bin
           Copy-Item -Recurse ${{ env.INSTALL_DIR }}/openvino_js_package node_modules/openvino-node/bin
 
+      - name: Check lint
+        working-directory: ${{ env.SRC_DIR }}/src/js
+        run: npm run lint
+
       - name: Run npm package tests
         working-directory: ${{ env.SRC_DIR }}/src/js
         run: npm test
 
-      - name: Install genai-node samples dependencies
+      - name: Install openvino-genai-node samples dependencies
         working-directory: ${{ env.SRC_DIR }}/samples/js/text_generation
         run: |
           npm install --verbose

samples/js/text_generation/chat_sample.js

@@ -1,5 +1,5 @@
 import readline from 'readline';
-import { Pipeline } from 'genai-node';
+import { LLMPipeline } from 'openvino-genai-node';
 
 main();
 
@@ -24,7 +24,7 @@ async function main() {
     output: process.stdout,
   });
 
-  const pipe = await Pipeline.LLMPipeline(MODEL_PATH, device);
+  const pipe = await LLMPipeline(MODEL_PATH, device);
   const config = { 'max_new_tokens': 100 };
 
   await pipe.startChat();

samples/js/text_generation/package-lock.json

@@ -1,11 +1,11 @@
 {
-  "name": "genai-node-demo",
+  "name": "openvino-genai-node-demo",
   "version": "1.0.0",
   "license": "Apache-2.0",
   "type": "module",
   "devDependencies": {
     "openvino-node": "^2025.0.0",
-    "genai-node": "file:../../../src/js/"
+    "openvino-genai-node": "file:../../../src/js/"
   },
   "engines": {
     "node": ">=21.0.0"

samples/js/text_generation/package.json

@@ -27,17 +27,17 @@ Then you can use OpenVINO™ GenAI JavaScript Bindings in one of the following w
 #### Option 1 - using npm:
 
 To use this package locally use `npm link` in `src/js/` directory
-and `npm link genai-node` in the folder where you want to add this package as a dependency
+and `npm link openvino-genai-node` in the folder where you want to add this package as a dependency
 
 #### Option 2 - using package.json:
 
-Add the `genai-node` package manually by specifying the path to the `src/js/` directory in your `package.json`:
+Add the `openvino-genai-node` package manually by specifying the path to the `src/js/` directory in your `package.json`:
 
 ```
-"genai-node": "file:*path-to-current-directory*"
+"openvino-genai-node": "file:*path-to-current-directory*"
 ```
 
 ### Verify the installation:
 ```sh
-node -e "const { Pipeline } = require('genai-node'); console.log(Pipeline);"
+node -e "const { Pipeline } = require('openvino-genai-node'); console.log(Pipeline);"
 ```

src/js/README.md

@@ -0,0 +1,35 @@
+import globals from 'globals';
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  {
+    languageOptions: { globals: globals.node },
+    rules: {
+      'semi': ['error'],
+      'no-var': ['error'],
+      'max-len': ['error', { 'ignoreUrls': true }],
+      'eol-last': ['error'],
+      'indent': ['error', 2],
+      'camelcase': ['error'],
+      'semi-spacing': ['error'],
+      'arrow-spacing': ['error'],
+      'comma-spacing': ['error'],
+      'no-multi-spaces': ['error'],
+      'quotes': ['error', 'single'],
+      'no-trailing-spaces': ['error'],
+      'space-before-blocks': ['error'],
+      'newline-before-return': ['error'],
+      'comma-dangle': ['error', 'always-multiline'],
+      'space-before-function-paren': ['error', {
+        named: 'never',
+        anonymous: 'never',
+        asyncArrow: 'always',
+      }],
+      'key-spacing': ['error', { beforeColon: false }],
+      'no-multiple-empty-lines': ['error', { max: 1, maxBOF: 0, maxEOF: 0 }],
+      'keyword-spacing': ['error', { overrides: { catch: { after: false } } }],
+      'prefer-destructuring': ['error', { object: true, array: false }],
+      '@typescript-eslint/no-var-requires': 0,
+    },
+  },
+];

src/js/eslint.config.js

@@ -0,0 +1,20 @@
+import { createRequire } from 'module';
+import { platform } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+
+// We need to use delayed import to get an updated Path if required
+function getGenAIAddon() {
+  const require = createRequire(import.meta.url);
+  const ovPath = require.resolve('openvino-node');
+  if (platform() == 'win32') {
+    // Find the openvino binaries that are required for openvino-genai-node
+    const pathToOpenVino = join(dirname(ovPath), '../bin');
+    if (!process.env.PATH.includes('openvino-node')) {
+      process.env.PATH += ';' + resolve(pathToOpenVino);
+    }
+  }
+
+  return require('../bin/genai_node_addon.node');
+}
+
+export default getGenAIAddon();

src/js/lib/addon.js

@@ -1,164 +1,12 @@
-import { createRequire } from 'module'
-import path from 'path';
-import util from 'node:util';
-import { platform } from 'node:os';
-import getGenAIAddon from './bindings.cjs';
+import { LLMPipeline as LLM } from './pipelines/llmPipeline.js';
 
-let ovPath;
-const require = createRequire(import.meta.url);
-try {
-  ovPath = require.resolve('openvino-node');
-} catch (error) {
-  if (error.code === 'MODULE_NOT_FOUND') {
-    console.error(error.message);
-  }
-  throw error;
-}
-
-if (platform() == "win32") {
-  // Find the openvino libraries that are required for genai-node
-  const pathToOpenVino = path.join(path.dirname(ovPath), '../bin');
-  if (!process.env.PATH.includes('openvino-node')) {
-    process.env.PATH += ';' + path.resolve(pathToOpenVino);
-  }
-}
-
-const addon = getGenAIAddon();
-
-class LLMPipeline {
-  modelPath = null;
-  device = null;
-  pipeline = null;
-  isInitialized = false;
-  isChatStarted = false;
-
-  constructor(modelPath, device) {
-    this.modelPath = modelPath;
-    this.device = device;
-  }
-
-  async init() {
-    if (this.isInitialized)
-      throw new Error('Pipeline is already initialized');
-
-    this.pipeline = new addon.LLMPipeline();
-
-    const init = util.promisify(this.pipeline.init.bind(this.pipeline));
-    const result = await init(this.modelPath, this.device);
-
-    this.isInitialized = true;
-
-    return result;
-  }
-
-  async startChat() {
-    if (this.isChatStarted)
-      throw new Error('Chat is already started');
-
-    const startChatPromise = util.promisify(
-      this.pipeline.startChat.bind(this.pipeline)
-    );
-    const result = await startChatPromise();
-
-    this.isChatStarted = true;
-
-    return result;
-  }
-  async finishChat() {
-    if (!this.isChatStarted)
-      throw new Error('Chat is not started');
-
-    const finishChatPromise = util.promisify(
-      this.pipeline.finishChat.bind(this.pipeline)
-    );
-    const result = await finishChatPromise();
-
-    this.isChatStarted = false;
-
-    return result;
-  }
-
-  static castOptionsToString(options) {
-    const castedOptions = {};
-
-    for (const key in options)
-      castedOptions[key] = String(options[key]);
-
-    return castedOptions;
-  }
-
-  getAsyncGenerator(prompt, generationOptions = {}) {
-    if (!this.isInitialized)
-      throw new Error('Pipeline is not initialized');
-
-    if (typeof prompt !== 'string')
-      throw new Error('Prompt must be a string');
-    if (typeof generationOptions !== 'object')
-      throw new Error('Options must be an object');
-
-    const castedOptions = LLMPipeline.castOptionsToString(generationOptions);
-
-    const queue = [];
-    let resolvePromise;
-
-    // Callback function that C++ will call when a chunk is ready
-    function chunkOutput(isDone, subword) {
-      if (resolvePromise) {
-        resolvePromise({ value: subword, done: isDone }); // Fulfill pending request
-        resolvePromise = null;  // Reset promise resolver
-      } else {
-        queue.push({ isDone, subword }); // Add data to queue if no pending promise
-      }
-    }
-
-    this.pipeline.generate(prompt, chunkOutput, castedOptions);
-
-    return {
-      async next() {
-        // If there is data in the queue, return it
-        // Otherwise, return a promise that will resolve when data is available
-        if (queue.length > 0) {
-          const { isDone, subword } = queue.shift();
-
-          return { value: subword, done: isDone };
-        }
-
-        return new Promise((resolve) => (resolvePromise = resolve));
-      },
-      [Symbol.asyncIterator]() { return this; }
-    };
-  }
-
-  async generate(prompt, generationOptions, generationCallback) {
-    const options = generationOptions || {};
-
-    if (generationCallback !== undefined && typeof generationCallback !== 'function')
-      throw new Error('Generation callback must be a function');
-
-    const g = this.getAsyncGenerator(prompt, options);
-    const result = [];
-
-    for await (const chunk of g) {
-      result.push(chunk);
-
-      if (generationCallback) generationCallback(chunk);
-    }
-
-    return result.join('');
-  }
-}
-
-class Pipeline {
+class PipelineFactory {
   static async LLMPipeline(modelPath, device = 'CPU') {
-    const pipeline = new LLMPipeline(modelPath, device);
+    const pipeline = new LLM(modelPath, device);
     await pipeline.init();
 
     return pipeline;
   }
 }
 
-
-export {
-  addon,
-  Pipeline,
-};
+export const {LLMPipeline} = PipelineFactory;

src/js/lib/bindings.cjs

@@ -0,0 +1,127 @@
+import util from 'node:util';
+import addon from '../addon.js';
+
+export class LLMPipeline {
+  modelPath = null;
+  device = null;
+  pipeline = null;
+  isInitialized = false;
+  isChatStarted = false;
+
+  constructor(modelPath, device) {
+    this.modelPath = modelPath;
+    this.device = device;
+  }
+
+  async init() {
+    if (this.isInitialized)
+      throw new Error('LLMPipeline is already initialized');
+
+    this.pipeline = new addon.LLMPipeline();
+
+    const initPromise = util.promisify(this.pipeline.init.bind(this.pipeline));
+    const result = await initPromise(this.modelPath, this.device);
+
+    this.isInitialized = true;
+
+    return result;
+  }
+
+  async startChat() {
+    if (this.isChatStarted)
+      throw new Error('Chat is already started');
+
+    const startChatPromise = util.promisify(
+      this.pipeline.startChat.bind(this.pipeline),
+    );
+    const result = await startChatPromise();
+
+    this.isChatStarted = true;
+
+    return result;
+  }
+  async finishChat() {
+    if (!this.isChatStarted)
+      throw new Error('Chat is not started');
+
+    const finishChatPromise = util.promisify(
+      this.pipeline.finishChat.bind(this.pipeline),
+    );
+    const result = await finishChatPromise();
+
+    this.isChatStarted = false;
+
+    return result;
+  }
+
+  static castOptionsToString(options) {
+    const castedOptions = {};
+
+    for (const key in options)
+      castedOptions[key] = String(options[key]);
+
+    return castedOptions;
+  }
+
+  getAsyncGenerator(prompt, generationOptions = {}) {
+    if (!this.isInitialized)
+      throw new Error('Pipeline is not initialized');
+
+    if (typeof prompt !== 'string')
+      throw new Error('Prompt must be a string');
+    if (typeof generationOptions !== 'object')
+      throw new Error('Options must be an object');
+
+    const castedOptions = LLMPipeline.castOptionsToString(generationOptions);
+
+    const queue = [];
+    let resolvePromise;
+
+    // Callback function that C++ will call when a chunk is ready
+    function chunkOutput(isDone, subword) {
+      if (resolvePromise) {
+        // Fulfill pending request
+        resolvePromise({ value: subword, done: isDone });
+        resolvePromise = null; // Reset promise resolver
+      } else {
+        // Add data to queue if no pending promise
+        queue.push({ isDone, subword });
+      }
+    }
+
+    this.pipeline.generate(prompt, chunkOutput, castedOptions);
+
+    return {
+      async next() {
+        // If there is data in the queue, return it
+        // Otherwise, return a promise that will resolve when data is available
+        if (queue.length > 0) {
+          const { isDone, subword } = queue.shift();
+
+          return { value: subword, done: isDone };
+        }
+
+        return new Promise((resolve) => (resolvePromise = resolve));
+      },
+      [Symbol.asyncIterator]() { return this; },
+    };
+  }
+
+  async generate(prompt, generationOptions, generationCallback) {
+
+    if (generationCallback !== undefined
+      && typeof generationCallback !== 'function')
+      throw new Error('Generation callback must be a function');
+
+    const g = this.getAsyncGenerator(prompt, generationOptions);
+    const result = [];
+
+    for await (const chunk of g) {
+      result.push(chunk);
+
+      if (generationCallback) generationCallback(chunk);
+    }
+
+    return result.join('');
+  }
+}

src/js/lib/module.js

@@ -1,7 +1,7 @@
 {
-  "name": "genai-node",
+  "name": "openvino-genai-node",
   "type": "module",
-  "version": "2024.5.0-preview",
+  "version": "2025.1.0-preview",
   "description": "OpenVINO™ GenAI pipelines for using from Node.js environment",
   "license": "Apache-2.0",
   "main": "./lib/module.js",
@@ -19,15 +19,26 @@
     "GenAI"
   ],
   "scripts": {
+    "lint": "eslint .",
     "test_setup": "node ./tests/setup.js",
-    "test": "npm run test_setup && node --test ./tests/*.test.js"
+    "test": "npm run test_setup && node --test ./tests/*.test.js",
+    "postinstall": "node ./scripts/download-runtime.cjs --ignore-if-exists"
   },
   "dependencies": {
     "openvino-node": "^2025.0.0"
   },
   "devDependencies": {
     "@huggingface/hub": "^0.21.0",
+    "eslint": "^9.20.1",
     "global-agent": "^3.0.0",
+    "globals": "^15.15.0",
     "node-fetch": "^3.3.2"
+  },
+  "binary": {
+    "version": "2025.1.0.0",
+    "module_path": "./bin/",
+    "remote_path": "./repositories/openvino_genai/nodejs_bindings/{version}/{platform}/",
+    "package_name": "openvino_genai_nodejs_bindings_{platform}_{version}_{arch}.tar.gz",
+    "host": "https://storage.openvinotoolkit.org"
   }
 }

src/js/lib/pipelines/llmPipeline.js

@@ -0,0 +1,23 @@
+const { join } = require('node:path');
+const BinaryManager = require('openvino-node/scripts/lib/binary-manager');
+
+const packageJson = require('../package.json');
+
+if (require.main === module) main();
+
+async function main() {
+  if (!BinaryManager.isCompatible()) process.exit(1);
+
+  const force = process.argv.includes('-f');
+  const ignoreIfExists = process.argv.includes('--ignore-if-exists');
+
+  const { env } = process;
+  const proxy = env.http_proxy || env.HTTP_PROXY || env.npm_config_proxy;
+
+  await BinaryManager.prepareBinary(
+    join(__dirname, '..'),
+    packageJson.binary.version || packageJson.version,
+    packageJson.binary,
+    { force, ignoreIfExists, proxy },
+  );
+}

src/js/package-lock.json

@@ -27,4 +27,4 @@ Napi::Object init_module(Napi::Env env, Napi::Object exports) {
 }
 
 // Register the addon with Node.js
-NODE_API_MODULE(genai-node, init_module)
+NODE_API_MODULE(openvino-genai-node, init_module)

src/js/package.json

@@ -1,4 +1,4 @@
-import { addon } from '../lib/module.js';
+import addon from '../lib/addon.js';
 
 import assert from 'node:assert';
 import { describe, it, before, after } from 'node:test';
@@ -53,6 +53,7 @@ describe('bindings', () => {
 
       assert.ok(output.length > 0);
       done();
+    // eslint-disable-next-line camelcase
     }, { temperature: '0', max_new_tokens: '4' });
   });
 });

src/js/scripts/download-runtime.cjs

@@ -1,4 +1,4 @@
-import { Pipeline } from '../lib/module.js';
+import { LLMPipeline } from '../lib/module.js';
 
 import assert from 'node:assert/strict';
 import { describe, it, before, after } from 'node:test';
@@ -11,7 +11,7 @@ describe('module', async () => {
   let pipeline = null;
 
   await before(async () => {
-    pipeline = await Pipeline.LLMPipeline(MODEL_PATH, 'CPU');
+    pipeline = await LLMPipeline(MODEL_PATH, 'CPU');
 
     await pipeline.startChat();
   });
@@ -23,6 +23,7 @@ describe('module', async () => {
   await it('should generate non empty string', async () => {
     const result = await pipeline.generate(
       'Type something in English',
+      // eslint-disable-next-line camelcase
       { temperature: '0', max_new_tokens: '4' },
       () => {},
     );
@@ -33,19 +34,19 @@ describe('module', async () => {
 
 describe('corner cases', async () => {
   it('should throw an error if pipeline is already initialized', async () => {
-    const pipeline = await Pipeline.LLMPipeline(MODEL_PATH, 'CPU');
+    const pipeline = await LLMPipeline(MODEL_PATH, 'CPU');
 
     await assert.rejects(
       async () => await pipeline.init(),
       {
         name: 'Error',
-        message: 'Pipeline is already initialized',
+        message: 'LLMPipeline is already initialized',
       },
     );
   });
 
   it('should throw an error if chat is already started', async () => {
-    const pipeline = await Pipeline.LLMPipeline(MODEL_PATH, 'CPU');
+    const pipeline = await LLMPipeline(MODEL_PATH, 'CPU');
 
     await pipeline.startChat();
 
@@ -59,7 +60,7 @@ describe('corner cases', async () => {
   });
 
   it('should throw an error if chat is not started', async () => {
-    const pipeline = await Pipeline.LLMPipeline(MODEL_PATH, 'CPU');
+    const pipeline = await LLMPipeline(MODEL_PATH, 'CPU');
 
     await assert.rejects(
       () => pipeline.finishChat(),
@@ -75,7 +76,7 @@ describe('generation parameters validation', () => {
   let pipeline = null;
 
   before(async () => {
-    pipeline = await Pipeline.LLMPipeline(MODEL_PATH, 'CPU');
+    pipeline = await LLMPipeline(MODEL_PATH, 'CPU');
 
     await pipeline.startChat();
   });
@@ -94,47 +95,54 @@ describe('generation parameters validation', () => {
     );
   });
 
-  it('should throw an error if generationCallback is not a function', async () => {
-    const pipeline = await Pipeline.LLMPipeline(MODEL_PATH, 'CPU');
+  it(
+    'should throw an error if generationCallback is not a function',
+    async () => {
+      const pipeline = await LLMPipeline(MODEL_PATH, 'CPU');
 
-    await pipeline.startChat();
+      await pipeline.startChat();
 
-    await assert.rejects(
-      async () => await pipeline.generate('prompt', {}, false),
-      {
-        name: 'Error',
-        message: 'Generation callback must be a function',
-      },
-    );
-  });
+      await assert.rejects(
+        async () => await pipeline.generate('prompt', {}, false),
+        {
+          name: 'Error',
+          message: 'Generation callback must be a function',
+        },
+      );
+    });
 
-  it('should throw an error if options specified but not an object', async () => {
-    await assert.rejects(
-      async () => await pipeline.generate('prompt', 'options', () => {}),
-      {
-        name: 'Error',
-        message: 'Options must be an object',
-      },
-    );
-  });
+  it(
+    'should throw an error if options specified but not an object',
+    async () => {
+      await assert.rejects(
+        async () => await pipeline.generate('prompt', 'options', () => {}),
+        {
+          name: 'Error',
+          message: 'Options must be an object',
+        },
+      );
+    });
 
   it('should perform generation with default options', async () => {
     try {
+      // eslint-disable-next-line camelcase
       await pipeline.generate('prompt', { max_new_tokens: 1 });
-    } catch (error) {
+    } catch(error) {
       assert.fail(error);
     }
 
     assert.ok(true);
   });
 
   it('should return a string as generation result', async () => {
+    // eslint-disable-next-line camelcase
     const reply = await pipeline.generate('prompt', { max_new_tokens: 1 });
 
     assert.strictEqual(typeof reply, 'string');
   });
 
   it('should call generationCallback with string chunk', async () => {
+    // eslint-disable-next-line camelcase
     await pipeline.generate('prompt', { max_new_tokens: 1 }, (chunk) => {
       assert.strictEqual(typeof chunk, 'string');
     });