Forem: flycran

smart-unit: The Elegant Unit Conversion Library JavaScript Developers Need

flycran — Sat, 14 Mar 2026 08:58:20 +0000

smart-unit: The Elegant Unit Conversion Library JavaScript Developers Need

Stop wrestling with rigid unit libraries. Format file sizes, lengths, time, and financial amounts with a single, intuitive API.

The Problem: Why Existing Solutions Fall Short

If you have ever tried to format file sizes in JavaScript, you know the pain. Most libraries force you into one of two uncomfortable positions:

Too specific: Libraries like bytes or filesize only handle file sizes. Need to format frequency, length, or currency? Install another dependency.
Too verbose: Generic conversion libraries require defining every conversion manually, creating bloated code for simple tasks.

// The old way: verbose and inflexible
const bytes = require('bytes');
const filesize = require('filesize');
// Still need something else for time, length, currency...

What if you could define any unit chain once and get intelligent formatting with a clean, minimal API?

Meet smart-unit

smart-unit is a lightweight TypeScript-first library that handles unit conversion with automatic unit selection. It is designed for developers who want elegance without sacrificing power.

npm install smart-unit

Core Concepts: Simple Yet Powerful

The genius of smart-unit lies in its declarative unit chain definition. You define your units and conversion ratios once, then let the library handle the rest.

File Size Formatting

import { SmartUnit } from 'smart-unit';

const fileSize = new SmartUnit(['B', 'KB', 'MB', 'GB', 'TB'], {
  baseDigit: 1024,
});

console.log(fileSize.format(1024));        // "1KB"
console.log(fileSize.format(1536));        // "1.5KB"
console.log(fileSize.format(1024 * 1024 * 100));  // "100MB"
console.log(fileSize.format(1024 * 1024 * 1024 * 5));  // "5GB"

Notice how format(1536) automatically selects "1.5KB" instead of "1536B" or "0.0015MB". The library intelligently picks the most readable unit.

Length Units with Variable Ratios

Not all unit systems use consistent base numbers. The metric system for length varies:

const length = new SmartUnit(['mm', 10, 'cm', 100, 'm', 1000, 'km']);

console.log(length.format(1500));      // "1.5m"
console.log(length.format(1500000));   // "1.5km"
console.log(length.format(25));        // "2.5cm"

By specifying individual ratios (10, 100, 1000), you can model any unit hierarchy accurately.

Bidirectional Conversion: Parse and Format

smart-unit is not just for display. It can parse formatted strings back to base values:

const time = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h']);

console.log(time.parse('90s'), 'ms');   // 90000 ms
console.log(time.parse('2.5h'), 'ms');  // 9000000 ms
console.log(time.parse('30m'), 'ms');   // 1800000 ms

This bidirectional capability makes it perfect for configuration files, user inputs, and data serialization.

High-Precision Mode: Beyond JavaScript's Limits

JavaScript's number type has a safe integer limit of 2^53 - 1 (about 9 quadrillion). For financial calculations or scientific applications, this is a dealbreaker.

smart-unit integrates with decimal.js for arbitrary-precision arithmetic:

const bigLength = new SmartUnit(['pm', 1000, 'nm', 1000, 'μm', 1000, 'mm', 1000, 'm'], {
  useDecimal: true,
});

console.log(bigLength.format('1000'));      // "1nm"
console.log(bigLength.format('1000000'));   // "1μm"

// BigInt support - beyond JS safe integer limit
const bigNumber = 123456789012345678901234567890n;
console.log('Formatted:', bigLength.format(bigNumber));

Financial Calculations

Currency and financial data often exceed safe integer limits while requiring precise decimal handling:

const currency = new SmartUnit(['', 'K', 'M', 'B', 'T'], {
  baseDigit: 1000,
  useDecimal: true,
  fractionDigits: 2,
});

console.log(currency.format('12345678901234567890'));  // "12345678.90T"

The fractionDigits: 2 ensures consistent decimal places for monetary values.

Why smart-unit Wins

Feature	bytes	filesize	smart-unit
File sizes	✅	✅	✅
Custom units	❌	❌	✅
Bidirectional	❌	❌	✅
High precision	❌	❌	✅
BigInt support	❌	❌	✅
TypeScript	Partial	Partial	✅ First-class
Bundle size	~1KB	~2KB	~2KB

smart-unit gives you the footprint of a specialized library with the flexibility of a generic one.

Real-World Use Cases

Data Transfer Rate

const bitrate = new SmartUnit(['bps', 'Kbps', 'Mbps', 'Gbps'], {
  baseDigit: 1000,
  fractionDigits: 1,
});

bitrate.format(1500000);  // "1.5Mbps"

Frequency

const freq = new SmartUnit(['Hz', 'kHz', 'MHz', 'GHz'], {
  baseDigit: 1000,
  fractionDigits: 2,
});

freq.format(2400000000);  // "2.40GHz"

Storage Capacity with Custom Thresholds

const storage = new SmartUnit(['B', 'KB', 'MB', 'GB', 'TB'], {
  baseDigit: 1024,
  threshold: 0.9,  // Switch units at 90% of next unit
});

TypeScript-First Design

smart-unit is written in TypeScript and provides full type safety:

import { SmartUnit } from 'smart-unit';
import type { Decimal } from 'decimal.js';

// Regular mode - returns number
const regular = new SmartUnit(['B', 'KB', 1024]);
const num: number = regular.parse('1KB');

// High-precision mode - returns Decimal
const precise = new SmartUnit(['B', 'KB', 1024], { useDecimal: true });
const dec: Decimal = precise.parse('1KB');

Type inference works seamlessly, and the API surface is intentionally small to minimize cognitive load.

Getting Started

npm install smart-unit

import { SmartUnit } from 'smart-unit';

// Define once, use everywhere
const size = new SmartUnit(['B', 'KB', 'MB', 'GB'], { baseDigit: 1024 });

size.format(1024 * 1024 * 100);  // "100MB"
size.parse('2.5GB');             // 2684354560

Try It Now

Experiment with smart-unit directly in your browser on CodeSandbox.

Conclusion

smart-unit solves a universal problem with an elegant solution. Whether you are formatting file uploads, parsing user input, handling financial data, or building scientific applications, it provides the right balance of simplicity and power.

Key takeaways:

Define any unit chain with minimal syntax
Automatic optimal unit selection
Bidirectional conversion (format and parse)
High-precision mode with BigInt support
TypeScript-first with minimal bundle size

Give it a try in your next project. Your unit conversion code will thank you.

Links:

GitHub: https://github.com/flycran/smart-unit
npm: https://www.npmjs.com/package/smart-unit
License: MIT

Develop a TypeScript language service plugin: Make RTK Query's "Go to Definition" smarter

flycran — Sun, 08 Mar 2026 07:27:34 +0000

Introduction

Have you ever encountered this frustration when developing with Redux Toolkit Query (RTK Query)?

When you want to check the implementation of an API endpoint, pressing F12 (Go to Definition) takes you to the type definition file instead of the actual business logic. You have to manually search for the endpoint name to find its definition in createApi.

This is a common problem because RTK Query hook names (like useGetUserQuery) are dynamically generated, and TypeScript cannot establish a static mapping from hook calls to endpoint definitions.

Today, I'll show you how to develop a TypeScript Language Service Plugin to solve this problem, allowing developers to jump directly to RTK Query endpoint definitions with a single click.

Problem Background

How RTK Query Works

RTK Query creates API slices through createApi:

export const userApi = createApi({
  reducerPath: 'userApi',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  endpoints: (builder) => ({
    getUser: builder.query<User, string>({
      query: (id) => `/users/${id}`,
    }),
    updateUser: builder.mutation<User, Partial<User>>({
      query: (body) => ({
        url: '/users',
        method: 'POST',
        body,
      }),
    }),
  }),
})

// Auto-generated hooks
export const { useGetUserQuery, useUpdateUserMutation } = userApi

Pain Points

Hook names are dynamically derived: getUser → useGetUserQuery
TypeScript only sees types: IDE's "Go to Definition" can only point to type gymnastics generated type definitions
Broken developer experience: Developers need to manually search for endpoint names, interrupting the coding flow

Solution: TypeScript Language Service Plugin

What is a Language Service Plugin?

TypeScript Language Service Plugin is an extension mechanism that allows us to intercept and customize various TypeScript language service operations, including:

Go to Definition
Auto Completion
Hover Information
Code Refactoring

Core Idea

Our plugin needs to accomplish the following:

Identify RTK Query Hooks: Recognize hooks like use{Endpoint}Query, use{Endpoint}Mutation through naming conventions
Parse AST: Find the API instance the hook belongs to
Locate Endpoint: Find the corresponding endpoint definition from the API instance's endpoints property
Return Definition Location: Point the jump target to the endpoint definition

Implementation Details

1. Project Structure

rtk-to-endpoints/
├── src/
│   ├── index.ts      # Plugin entry
│   └── utils.ts      # Core logic
├── package.json
└── tsconfig.json

2. Plugin Entry (index.ts)

import tslib from "typescript/lib/tsserverlibrary";
import { getDefinitionAndBoundSpan } from "./utils.js";

function init(modules: { typescript: typeof tslib }) {
  const ts = modules.typescript;

  function create(info: tslib.server.PluginCreateInfo) {
    const logger = info.project.projectService.logger;

    log("✅ Plugin initialized");

    const proxy: tslib.LanguageService = Object.create(info.languageService);

    // Intercept "Go to Definition" request
    proxy.getDefinitionAndBoundSpan = (
      fileName: string,
      position: number
    ): tslib.DefinitionInfoAndBoundSpan | undefined => {
      const program = info.languageService.getProgram();

      // Try our custom jump logic
      const definitionInfo = getDefinitionAndBoundSpan(
        fileName, position, ts, program
      );

      // If RTK Query hook is matched, return custom result
      // Otherwise, fall back to default behavior
      return definitionInfo || 
        info.languageService.getDefinitionAndBoundSpan(fileName, position);
    };

    return proxy;
  }

  return { create };
}

export = init;

3. Core Logic (utils.ts)

3.1 Recognizing Hook Naming Patterns

RTK Query generated hooks follow fixed naming conventions:

const HOOK_PREFIXES = ["useLazy", "use"] as const;
const HOOK_SUFFIXES = [
  "InfiniteQueryState",
  "InfiniteQuery", 
  "QueryState",
  "Mutation",
  "Query",
] as const;

// Extract endpoint name from hook name
export function extractEndpointName(hookName: string) {
  for (const prefix of HOOK_PREFIXES) {
    if (hookName.startsWith(prefix)) {
      const rest = hookName.slice(prefix.length);
      for (const suffix of HOOK_SUFFIXES) {
        if (rest.endsWith(suffix)) {
          const endpointName = rest.slice(0, rest.length - suffix.length);
          if (endpointName) {
            // Lowercase first letter: GetUser → getUser
            return endpointName[0].toLowerCase() + endpointName.slice(1);
          }
        }
      }
    }
  }
}

3.2 AST Node Lookup

Use binary search to quickly locate the node at cursor position in the AST:

export function getIdentifierNodeAt(
  sourceFile: tslib.SourceFile,
  pos: number,
): tslib.Node | undefined {
  let current: tslib.Node = sourceFile;

  while (true) {
    const children = current.getChildren(sourceFile);
    let left = 0;
    let right = children.length - 1;
    let targetChild: tslib.Node | undefined;

    // Binary search for child node covering the specified position
    while (left <= right) {
      const mid = (left + right) >>> 1;
      const child = children[mid];
      if (pos < child.pos) {
        right = mid - 1;
      } else if (pos >= child.end) {
        left = mid + 1;
      } else {
        targetChild = child;
        break;
      }
    }

    if (!targetChild) break;
    current = targetChild;
  }

  return current;
}

3.3 Finding API Instance

Support two common API usage patterns:

export function findApi(node: tslib.Node, ts: typeof tslib) {
  const parent = node.parent;

  // Pattern 1: Destructuring assignment
  // const { useGetUsersQuery } = userApi
  if (ts.isBindingElement(parent)) {
    const expressionNode = parent.parent?.parent;
    if (!ts.isVariableDeclaration(expressionNode)) return;
    const apiNode = expressionNode.getChildAt(
      expressionNode.getChildCount() - 1
    );
    if (!apiNode || !ts.isIdentifier(apiNode)) return;
    return apiNode;

  // Pattern 2: Property access
  // userApi.useGetProductsQuery()
  } else if (parent && ts.isPropertyAccessExpression(parent)) {
    return parent.getChildAt(parent.getChildCount() - 3);
  }
}

3.4 Locating Endpoint Definition

Use TypeScript's type checker to find the target endpoint from the API instance's endpoints property:

export function findEndpoint(
  apiNode: tslib.Node, 
  endpointName: string, 
  checker: tslib.TypeChecker
) {
  // Get the type of API instance
  const apiType = checker.getTypeAtLocation(apiNode);

  // Get endpoints property
  const endpointsSymbol = apiType.getProperty('endpoints');
  if (!endpointsSymbol) return;

  // Get the type of endpoints
  const endpointsType = checker.getTypeOfSymbol(endpointsSymbol);

  // Find specific endpoint
  const endpointsPropertySymbol = endpointsType.getProperty(endpointName);
  return endpointsPropertySymbol;
}

3.5 Assembling Definition Information

export function getDefinitionAndBoundSpan(
  fileName: string, 
  position: number, 
  ts: typeof tslib, 
  program?: tslib.Program
) {
  const sf = program!.getSourceFile(fileName);
  const checker = program!.getTypeChecker();
  if (!sf || !program || !checker) return;

  // 1. Find identifier node at cursor position
  const identNode = getIdentifierNodeAt(sf, position);
  if (!identNode || !ts.isIdentifier(identNode)) return;

  // 2. Extract endpoint name
  const endpointName = extractEndpointName(identNode.getText());
  if (!endpointName) return;

  // 3. Find API instance
  const apiNode = findApi(identNode, ts);
  if (!apiNode) return;

  // 4. Find endpoint definition
  const endpointSymbol = findEndpoint(apiNode, endpointName, checker);
  if (!endpointSymbol?.declarations?.length) return;

  // 5. Assemble definition information
  const definitions = endpointSymbol.declarations.map((node): tslib.DefinitionInfo => {
    return {
      fileName: node.getSourceFile().fileName,
      kind: ts.ScriptElementKind.memberFunctionElement,
      name: endpointSymbol.getName(),
      containerKind: ts.ScriptElementKind.classElement,
      containerName: "endpoints",
      textSpan: {
        start: node.getStart(),
        length: node.getWidth(),
      },
    };
  });

  return {
    definitions,
    textSpan: {
      start: identNode.getStart(sf),
      length: identNode.getWidth(sf),
    },
  };
}

Usage

1. Install the Plugin

npm install --save-dev rtk-to-endpoints

2. Configure tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "rtk-to-endpoints"
      }
    ]
  }
}

3. Configure VSCode

Since VSCode's built-in TypeScript cannot read npm packages from the project, you need to set VSCode to use the workspace TypeScript version:

Ctrl+Shift+P → Type "TypeScript: Select TypeScript Version"
Select "Use Workspace Version"
Reload window (Developer: Reload Window)

Demo

After configuration, when you use "Go to Definition" on any RTK Query hook:

// Click useGetUserQuery to jump directly to getUser endpoint definition
const { data } = userApi.useGetUserQuery(userId);

Before:

Points to type definition file (no practical business value)

After:

Directly locates the getUser endpoint definition in createApi

Technical Summary

1. TypeScript Language Service Architecture

┌─────────────────────────────────────────┐
│           VSCode / IDE                  │
└─────────────┬───────────────────────────┘
              │ LSP Protocol
┌─────────────▼───────────────────────────┐
│      TypeScript Language Server         │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│    TypeScript Language Service          │
│  ┌─────────────────────────────────┐    │
│  │  rtk-to-endpoints Plugin        │    │
│  │  (Intercept getDefinition)      │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

2. Key Technical Points

Technical Point	Description
AST Traversal	Use binary search to efficiently locate nodes
Type Checker	Use `TypeChecker` to parse type information
Proxy Pattern	Wrap original Language Service, preserve default behavior
Naming Resolution	Identify hook types through string pattern matching

Extension Ideas

The implementation of this plugin can be extended to other similar scenarios:

Vue Composition API: Jump from useXxx to composable definitions
React Hooks: Enhance custom hook navigation experience

Conclusion

TypeScript Language Service Plugin is a powerful tool that can significantly improve the developer experience. By understanding TypeScript's compiler API and language service architecture, we can build smarter IDE support for specific frameworks and libraries.

I hope this article helps you understand how Language Service Plugins work and inspires you to develop similar tools for your own projects.

References

If this article helped you, please like, bookmark, and share!

Feel free to leave comments if you have any questions or suggestions.