Crate sublime_node_tools 

sublime_node_tools

Node.js bindings for Sublime Workspace CLI Tools via napi-rs.

What

This crate provides Node.js bindings via napi-rs for the workspace-tools CLI, exposing 23 execute functions as native JavaScript/TypeScript functions. It enables Node.js and TypeScript applications to use workspace-tools functionality programmatically without spawning CLI processes.

How

The crate uses #[napi] macros to:

• Define async functions callable from Node.js
• Convert Rust types to JavaScript objects via #[napi(object)]
• Generate TypeScript definitions automatically

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         JavaScript/TypeScript                        │
│                                                                      │
│   const result = await status({ root: "/path/to/project" });        │
│                                                                      │
│   if (result.success) {                                             │
│     console.log(result.data.packages);  // ← Native JS objects      │
│   } else {                                                          │
│     console.error(result.error.code);   // ← "EVALIDATION"          │
│   }                                                                 │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      NAPI Layer (crates/node/)                       │
│                                                                      │
│   1. Parameter validation (validation.rs)                           │
│   2. Conversion JS → Rust structs                                   │
│   3. Call execute_* functions from CLI                              │
│   4. Capture JSON output                                            │
│   5. Parse and convert to NAPI structs                              │
│   6. Return ApiResponse<T>                                          │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      CLI Layer (crates/cli/)                         │
│                                                                      │
│   execute_status(), execute_init(), execute_changeset_add(), ...    │
└─────────────────────────────────────────────────────────────────────┘

Module Structure

• error: Error handling with Node.js-style error codes (EVALIDATION, EGIT, etc.)
• validation: Parameter validation before CLI execution
• response: ApiResponse<T> wrapper for consistent success/error responses
• types: NAPI-compatible structs for parameters and responses
• commands: Implementation of all 23 NAPI functions

Why

Enables Node.js/TypeScript applications to use workspace-tools functionality programmatically without spawning CLI processes, with:

• Full type safety: TypeScript definitions are auto-generated
• Native performance: Direct function calls instead of process spawning
• Structured responses: ApiResponse<T> with success/error handling
• Node.js-style errors: Familiar error codes like ENOENT, EVALIDATION

Examples

Basic Usage

import { status, changesetAdd, bumpPreview } from '@websublime/workspace-tools';

// Get workspace status
const result = await status({ root: '.' });
if (result.success) {
  console.log(result.data.packages);
} else {
  console.error(`Error [${result.error.code}]: ${result.error.message}`);
}

Error Handling

import { changesetAdd } from '@websublime/workspace-tools';

const result = await changesetAdd({
  root: '.',
  packages: ['@scope/pkg1'],
  bumpType: 'minor',
  message: 'Add new feature'
});

if (!result.success) {
  switch (result.error.code) {
    case 'EVALIDATION':
      console.error('Invalid parameters:', result.error.message);
      break;
    case 'EGIT':
      console.error('Git error:', result.error.message);
      break;
    default:
      console.error('Unexpected error:', result.error.message);
  }
}

Constants

VERSION

Version of the crate.

Functions

get_version

Returns the version of the crate.