Forem: Shahrad Elahi

A Modern, Immutable, and Zero-Dependency Library for IP Addresses in JavaScript

Shahrad Elahi — Thu, 30 Oct 2025 04:48:13 +0000

The IP Address Library You've Been Waiting For

Ever found yourself wrestling with IP addresses in a Node.js application? Maybe you're validating user input, checking if an IP belongs to a certain subnet, or just trying to convert between different formats. While there are libraries out there, many feel a bit dated or come with a baggage of dependencies.

What if there was a modern, clean, and powerful way to handle this?

Meet @se-oss/ip-address! It's a brand-new, zero-dependency library designed from the ground up for modern JavaScript and TypeScript development. It provides an immutable, intuitive API for both IPv4 and IPv6 addresses and CIDR ranges.

Why Another IP Library?

That's a fair question. Here’s what makes @se-oss/ip-address different:

Immutable API: Create an IP object once, and it can't be changed. Operations like next() or previous() return a new instance, preventing bugs from accidental modifications.
Zero Dependencies: It's lightweight and secure. No need to worry about a bloated node_modules folder or transitive dependency vulnerabilities.
TypeScript First: Written entirely in TypeScript, offering excellent autocompletion and type safety out of the box.
Comprehensive: Handles IPv4, IPv6, and CIDR notation with a consistent, easy-to-use API.

Getting Started

Installation is as simple as you'd expect.

pnpm install @se-oss/ip-address

Or if you prefer npm or yarn:

# npm
npm install @se-oss/ip-address

# yarn
yarn add @se-oss/ip-address

The Fun Part: Code Examples

Let's dive into what you can do with it.

Parsing and Validation

The library makes it trivial to parse and validate any IP address. The parseIP factory automatically detects the IP version.

import { IPv4, IPv6, parseIP } from '@se-oss/ip-address';

// Let the factory do the work
const ip = parseIP('192.168.1.1'); // Returns an IPv4 instance
const ip6 = parseIP('2001:db8::1'); // Returns an IPv6 instance

console.log(ip.version); // 4
console.log(ip6.version); // 6

// Or validate without creating an instance
if (IPv4.isValid('10.0.0.1')) {
  console.log('Yep, a valid IPv4 address.');
}

// It throws a specific error for invalid addresses
try {
  parseIP('not.an.ip');
} catch (error) {
  console.error(error.message); // "Invalid IP address: not.an.ip"
}

Working with IPv4 Addresses

Once you have an IPv4 instance, you can perform all sorts of checks and conversions.

import { IPv4 } from '@se-oss/ip-address';

const ip = new IPv4('192.168.1.1');

// Check its type
console.log(ip.isPrivate()); // true
console.log(ip.isLoopback()); // false

// Convert it to other formats
console.log(ip.toBigInt()); // 3232235777n
console.log(ip.toBytes()); // [192, 168, 1, 1]
console.log(ip.toArpa()); // "1.1.168.192.in-addr.arpa"

// Get the next IP (returns a new instance!)
const nextIp = ip.next();
console.log(nextIp.address); // "192.168.1.2"

IPv6 is a First-Class Citizen

IPv6 is just as easy, with full support for its unique features, like handling IPv4-mapped addresses.

import { IPv6 } from '@se-oss/ip-address';

const ip6 = new IPv6('2001:db8::8a2e:370:7334');

// Get compressed vs. expanded address
console.log(ip6.address); // "2001:db8::8a2e:370:7334"
console.log(ip6.expandedAddress); // "2001:0db8:0000:0000:0000:8a2e:0370:7334"

// Check its type
console.log(ip6.isGlobalUnicast()); // true

// Handle IPv4-mapped addresses seamlessly
const mappedIp = new IPv6('::ffff:192.168.1.1');
console.log(mappedIp.isIPv4Mapped()); // true

const ipv4 = mappedIp.toIPv4();
console.log(ipv4.address); // "192.168.1.1"

Mastering Subnets with CIDR

Need to work with subnets? The CIDR class has you covered. This is incredibly useful for network calculations.

import { CIDR } from '@se-oss/ip-address';

const cidr = new CIDR('10.0.0.0/24');

// Get network details
console.log(cidr.network.address); // "10.0.0.0"
console.log(cidr.broadcast.address); // "10.0.0.255"
console.log(cidr.first.address); // "10.0.0.1" (First usable IP)
console.log(cidr.last.address); // "10.0.0.254" (Last usable IP)

// Check if an IP falls within the range
console.log(cidr.contains('10.0.0.123')); // true
console.log(cidr.contains('10.0.1.1')); // false

Under the Hood

One of the reasons this library is so precise is its use of native BigInt. This allows for accurate calculations on large 128-bit IPv6 addresses without running into floating-point limitations that can plague number-based approaches.

Final Thoughts

Whether you're building a security tool, a network scanner, or just need to handle IP data reliably in your web application, @se-oss/ip-address offers a clean, modern, and safe API to get the job done. It's lightweight, has no dependencies, and its immutable design can help you write more predictable code.

Give it a try! Check out the GitHub repository to see the source, and don't forget to leave a star if you find it useful. We welcome contributions and feedback!

Stop Leaking Your Secrets! Secure Your Node.js Environment Variables.

Shahrad Elahi — Fri, 29 Aug 2025 19:17:32 +0000

Let's be real: we all sling secrets in .env files. It's the default for a reason. You drop your DATABASE_URL and API_KEY in there, load them up, and you're off to the races.

But have you ever stopped to think about what happens after you load them into process.env?

So, What's the Big Deal?

When you dump everything into process.env, you're essentially tossing your secrets into a global free-for-all. Every single package in your node_modules black hole—and all of their dependencies—can take a peek.

Usually, that's fine. But in an ecosystem this massive, it only takes one sketchy dependency or one compromised package to start hoovering up your sensitive data. That nagging feeling in the back of your head? It's probably justified.

A "Virtual Environment" for Your Env Vars

This exact worry is why I built process-venv. It's a simple idea: create a "virtual environment" for your config. Instead of exposing everything, it keeps your variables in a safe, isolated container. Only the variables you explicitly mark as "shared" will ever touch process.env.

Here's the payoff:

Keep Your Secrets Actually Secret: Your API_KEY stays tucked away, safe from prying eyes in your dependency tree.
Fail-Fast with Schema Validation: Using tools you already love like Zod, Valibot, or ArkType, you can validate your env vars on startup. No more chasing down undefined errors at 3 AM.
No More Runtime Shenanigans: The environment is immutable. Once it's loaded, it's locked. No accidental (or malicious) changes during runtime.

Let's See It in Action

Here’s how easy it is to get started. First, grab the packages:

pnpm install process-venv zod

(We're using Zod here, but any Standard Schema validator will do.)

Next, set up your environment config. I like to do this in its own file.

// src/env.ts
import { createEnv } from 'process-venv';
import * as z from 'zod';

export const venv = createEnv({
  // Define the shape of your environment variables.
  // Zod is great for this.
  schema: {
    NODE_ENV: z
      .enum(['development', 'production', 'test'])
      .default('development'),
    PORT: z.coerce.number().default(3000),
    DATABASE_URL: z.string().url(),
    API_KEY: z.string(), // This will be private by default.
    SHARED_SECRET: z.string(), // We'll share this one.
  },

  // Now, tell process-venv which variables are safe to expose globally.
  // These are usually things your framework needs.
  shared: ['NODE_ENV', 'PORT', 'SHARED_SECRET'],
});

Now, in the rest of your app, you just import and use it.

// src/index.ts
import { venv } from './env';

// Things like your web framework can still access what they need.
console.log('NODE_ENV from process.env:', process.env.NODE_ENV);

// But you access everything else from the safe venv instance.
console.log('API_KEY from venv:', venv.API_KEY);
console.log('PORT from venv:', venv.PORT);

// And here's the magic: your API key is nowhere to be found globally.
console.log('API_KEY from process.env:', process.env.API_KEY);
// => undefined

That's it. Your API_KEY is now available to your code via the venv object, but it's invisible to the rest of process.env. Peace of mind.

Give It a Spin!

I'd be thrilled if you gave process-venv a try in your next project. It's a small change that can make a real difference in your app's security posture.

You can find it on npm and the source is on GitHub.

If you dig it, a star on GitHub would be awesome! Let me know what you think in the comments. Cheers!

Solving Distributed ID Challenges with Snowflake IDs in TypeScript

Shahrad Elahi — Wed, 27 Aug 2025 12:19:58 +0000

Generating unique identifiers in distributed systems is a common headache. Traditional methods like auto-incrementing database IDs hit scaling limits, and UUIDs, while unique, lack inherent sortability. What if there was an ID that was both unique and time-ordered?

Here's where Snowflake IDs come into play.

Originally from Twitter, Snowflake IDs are unique, time-ordered, 64-bit identifiers perfect for high-throughput, distributed environments. Today, I want to introduce you to @se-oss/snowflake-sequence, a lightweight, high-performance TypeScript library that brings Snowflake IDs directly to your Node.js applications.

Why Snowflake IDs?

Snowflake IDs solve key problems in distributed systems:

Scalability: Generated locally on each node, avoiding central bottlenecks.
Sortability: Embeds a timestamp, so newer IDs are always greater than older ones.
Uniqueness: Virtually guaranteed across your entire system.
Efficiency: A compact 64-bit integer.

This is where @se-oss/snowflake-sequence shines, offering a robust and easy-to-use implementation.

Anatomy of a Snowflake ID

A Snowflake ID is a 64-bit integer composed of three parts:

Timestamp (41 bits): Milliseconds since a custom epoch. This enables time-based sorting.
Node ID (10 bits): A unique identifier for the generating machine or process (0-1023).
Sequence (12 bits): Increments for IDs generated within the same millisecond on the same node (up to 4096 per millisecond).

The library handles all the complex bitwise operations for you.

Getting Started with `@se-oss/snowflake-sequence`

Install it with pnpm (or your preferred package manager):

pnpm install @se-oss/snowflake-sequence

Generate and deconstruct IDs:

import { Snowflake } from '@se-oss/snowflake-sequence';

// 1. Create a new Snowflake generator instance.
//    The nodeId is crucial for uniqueness across your distributed system.
//    The epoch is optional; it defaults to Twitter's original epoch.
const snowflake = new Snowflake({
  nodeId: 42, // Unique ID for this service instance (0-1023)
  epoch: 1672531200000, // Optional: Jan 1, 2023, 00:00:00 UTC
});

// 2. Generate a new Snowflake ID.
const id = snowflake.nextId();
console.log(`Generated ID: ${id}n`); // Notice the 'n' for BigInt

// 3. Deconstruct the ID to inspect its components.
const deconstructed = Snowflake.deconstruct(id);
console.log('Deconstructed ID:', deconstructed);
/*
Output will be something like:
{
  timestamp: 1672531200000n + some_milliseconds_since_epoch,
  nodeId: 42n,
  sequence: 0n, // or higher if multiple IDs were generated in the same millisecond
  epoch: 1288834974657n // Note: deconstruct uses the DEFAULT_EPOCH for consistency
}
*/

Customization and Robustness

Configure your Snowflake generator for your environment:

Node ID: Assign a unique nodeId (0-1023) to each service instance, perhaps via environment variables or service discovery (like Consul or Eureka).
Epoch: Set a custom epoch timestamp to maximize ID lifespan or align with existing systems.

The library also handles edge cases:

Clock Backwards: Throws an error if the system clock moves backward, preventing non-unique IDs.
Sequence Rollover: Automatically waits for the next millisecond if more than 4096 IDs are generated in a single millisecond, ensuring uniqueness.

Real-World Applications

Snowflake IDs are ideal for:

Distributed Logging: Chronological sorting of logs across services.
Event Sourcing: Unique and ordered event IDs.
User-Generated Content: Efficiently sort and retrieve posts, comments, etc.

Under the Hood: The Bitwise Magic

The efficiency of Snowflake IDs comes from clever bitwise operations that pack the timestamp, node ID, and sequence into a single 64-bit BigInt.

Imagine the 64 bits of the ID:

[ 0 | 41-bit Timestamp | 10-bit Node ID | 12-bit Sequence ]

Here's a simplified look at how it works:

Generating an ID:

Timestamp: The difference between the current time and the chosen epoch is calculated. This 41-bit value is shifted left by TIMESTAMP_SHIFT (which is NODE_ID_BITS + SEQUENCE_BITS = 10 + 12 = 22 bits). This moves the timestamp to the leftmost significant position.
Node ID: Your nodeId (10 bits) is shifted left by NODE_ID_SHIFT (which is SEQUENCE_BITS = 12 bits). This places the node ID in its designated 10-bit slot.
Sequence: The sequence number (12 bits) is added directly, occupying the rightmost 12 bits.

These three shifted values are then combined using the bitwise OR (|) operator to form the final 64-bit Snowflake ID.

Deconstructing an ID:

To get the components back:

Timestamp: The ID is shifted right by TIMESTAMP_SHIFT to isolate the timestamp, and then the epoch is added back to get the absolute timestamp.
Node ID: The ID is shifted right by NODE_ID_SHIFT and then a bitwise AND (&) operation with MAX_NODE_ID (a mask of 10 ones) is used to extract just the 10-bit node ID.
Sequence: A bitwise AND (&) operation with MAX_SEQUENCE (a mask of 12 ones) directly extracts the 12-bit sequence number.

This direct manipulation of bits is what makes Snowflake ID generation and deconstruction incredibly fast and efficient.

Conclusion & Call to Action

Snowflake IDs offer a scalable, unique, and time-sortable solution for distributed ID generation. The @se-oss/snowflake-sequence library provides a high-performance, pure TypeScript implementation that's easy to integrate.

If you're building distributed systems, give @se-oss/snowflake-sequence a try!

GitHub: shahradelahi/snowflake-sequence
Install: pnpm install @se-oss/snowflake-sequence

Happy coding!