Forem: johnretsas

NPM package - find-circular

johnretsas — Wed, 09 Apr 2025 09:51:22 +0000

Detecting Circular References in JavaScript Objects with `find-circular`

When working with JavaScript objects, dealing with circular references can be a tricky and frustrating challenge. Circular references occur when an object references itself directly or indirectly, leading to infinite loops or errors when trying to serialize the object with JSON.stringify. Fortunately, the find-circular npm package offers a simple and effective way to detect and handle circular references in objects.

Why Circular References Matter

Circular references can cause issues when you attempt to serialize objects into JSON, a common operation in web development. For example:

const obj = { a: 1 };
obj.self = obj;

JSON.stringify(obj);
// Throws a TypeError: Converting circular structure to JSON

The error above happens because JSON.stringify doesn't know how to handle the circular reference (obj.self pointing back to obj). This is where find-circular shines – it identifies these circular references and replaces them with a placeholder ("[Circular]"), preventing errors and making the object safe for serialization.

Introducing `find-circular`

find-circular is a lightweight utility designed to detect and handle circular references in JavaScript objects. It’s easy to install and use, making it a go-to solution for debugging or cleaning objects with potential circular references.

Installation

To get started, install the package using npm:

npm install find-circular

How to Use `find-circular`

Here’s a quick example to demonstrate how find-circular works:

import { findCircular } from "find-circular";

// Create an object with a circular reference
const obj = { a: 1 };
obj.self = obj;

// Detect and handle the circular reference
console.log(findCircular(obj));
// Output: { a: 1, self: "[Circular]" }

What’s Happening Here?

The findCircular function traverses the object and detects any references that point back to an earlier object in the traversal chain. When it finds a circular reference, it replaces it with the string "[Circular]".

Use Cases for `find-circular`

1. Debugging Complex Data Structures

When dealing with deeply nested or dynamic objects, find-circular helps uncover circular references that might otherwise go unnoticed.

2. Safe Serialization

If you need to serialize objects for APIs, logging, or storage, find-circular ensures circular references won’t cause your application to crash.

3. Object Inspection

Developers can use find-circular to inspect objects safely in debugging tools or during runtime.

Source Code and Contributions

The find-circular package is open-source and welcomes contributions! You can explore the source code or raise issues on the [GitHub repository]. Whether you’re looking to add new features, report bugs, or improve documentation, your input is valued.

Why Use `find-circular`?

Simplicity: A lightweight utility that gets the job done with minimal setup.
Reliability: Handles circular references gracefully, ensuring your objects remain usable.
Open Source: Actively maintained with opportunities to contribute and collaborate.

Final Thoughts

Managing circular references doesn’t have to be a headache. With find-circular, you can quickly identify and handle problematic references, making your objects safe for serialization and inspection. Give it a try in your next project and simplify how you handle complex JavaScript objects.

Getting Started with a Node.js TypeScript Boilerplate

johnretsas — Mon, 09 Dec 2024 09:12:53 +0000

Getting Started with a Node.js TypeScript Boilerplate using esbuild

Setting up a modern Node.js project with TypeScript, Axios, and ESLint provides a solid foundation for building scalable applications. But what if you want a fast and efficient bundling tool to speed up your development process? Enter esbuild—a fast bundler and minifier that will help you compile TypeScript code and bundle your application with ease.

In this blog post, we will walk through setting up a Node.js project with TypeScript, using esbuild for bundling, and integrating Axios for HTTP requests and ESLint for maintaining code quality.

Why Use TypeScript for Node.js?

TypeScript provides type safety and improved tooling over plain JavaScript, allowing you to catch errors early and build maintainable applications. Benefits of using TypeScript include:

Type Safety: Helps to catch type errors before runtime, reducing bugs.
Enhanced Developer Experience: Tools like autocompletion and inline documentation make coding easier.
Better Refactoring: The strict typing allows for safer, easier code refactoring.

Why Use esbuild?

While TypeScript provides the structure and safety for your code, bundlers like esbuild help with bundling your TypeScript files into a single, optimized output for deployment. Esbuild offers:

Lightning-fast performance: esbuild is known for its speed, offering quick builds and fast rebuilds during development.
Built-in minification: Minifying your code for production is easy with esbuild.
Simple configuration: It’s simple to set up and integrates well with TypeScript projects.

Features of the Node.js TypeScript Boilerplate with esbuild

This boilerplate includes everything you need to get started:

TypeScript: The project is configured to use modern TypeScript with ESNext module support, enabling the latest JavaScript features.
Axios: Axios is pre-configured for making HTTP requests.
ESLint: To ensure your code follows consistent coding standards.
esbuild: Used for bundling your TypeScript code into a single output file.
Type Declarations: Automatic generation of .d.ts files for type support and IDE autocompletion.

How to Set Up the Node.js TypeScript Boilerplate

Step 1: Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/johnretsas/node-ts-boilerplate.git
cd node-ts-boilerplate

Step 2: Install Dependencies

Run the following command to install the necessary dependencies:

npm install

This will install all required packages, including TypeScript, Axios, ESLint, esbuild, and tsx.

Step 3: Run the Project

Development Mode

To start the application in development mode with hot-reloading, run:

npm run dev

This will use tsx to automatically reload the application when changes are detected in the source files.

Build the Application

To compile your TypeScript code into a bundled JavaScript file using esbuild, run:

npm run build

The build.js script uses esbuild to bundle your TypeScript files and outputs the result to dist/bundle.js.

Here's a quick look at the build.js script:

import { build } from 'esbuild';

const isProd = process.env.NODE_ENV === 'production'; // Check if we're in production

build({
  entryPoints: ['./src/index.ts'],
  bundle: true,
  outfile: './dist/bundle.js',
  resolveExtensions: ['.ts', '.tsx', '.js', '.json'],
  sourcemap: !isProd, // Enable source maps in development
  minify: isProd, // Minify in production
  target: 'esnext', // Target modern JavaScript
}).catch(() => process.exit(1)); // Exit process if build fails

Start the Application

Once the project is built, you can start the application with:

npm start

This will run the compiled bundle.js from the dist/ folder.

Clean Build Files

To remove the compiled build files, run:

npm run clean

Step 4: Lint Your Code

To maintain code quality, run ESLint to check for errors or issues:

npm run lint

This will run ESLint across your project and provide feedback on any issues.

Step 5: Type Checking

You can perform type checking to ensure that your TypeScript code is correctly typed without generating output files using:

npm run type-check

This will validate the types in your TypeScript files based on the settings in your tsconfig.json.

Development vs. Production

In your build process, it’s important to distinguish between development and production environments. In development, you want fast rebuilds with source maps enabled for easier debugging. In production, however, you should minify your code to reduce file size and improve load times.

The build.js script checks the NODE_ENV environment variable to adjust the configuration for each environment:

Development: Enables source maps and skips minification for faster rebuilds.
Production: Minifies the code to reduce file size and excludes source maps.

Conclusion

This boilerplate gives you a fast and efficient way to develop and bundle your Node.js applications with TypeScript, Axios, ESLint, and esbuild. By using esbuild for bundling, you're getting a lightning-fast build process, and the combination of TypeScript and Axios ensures a robust and maintainable codebase.

For more information on the tools used in this boilerplate, check out the following resources: