@verifyhash/ip-cidr 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+Copyright (c) 2026 verifyhash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,10 +8,15 @@ ip↔integer conversion.
 
 No network access, no runtime dependencies, no servers. Just math on the bits.
 
-> **Package name is a placeholder.** The manifest name is
-> `PLACEHOLDER-ip-cidr`. TODO: the owner picks the final npm name/scope before
-> any publish. This library is **not published** — graduation to npm is a
-> human-gated step.
+## Install
+
+```bash
+npm install @verifyhash/ip-cidr
+```
+
+Published as [`@verifyhash/ip-cidr`](https://www.npmjs.com/package/@verifyhash/ip-cidr);
+source lives in the [verifyhash/libs](https://github.com/verifyhash/libs) monorepo.
+Zero runtime dependencies — you can also vendor the folder directly.
 
 ## Who it's for
 
@@ -24,11 +29,11 @@ No network access, no runtime dependencies, no servers. Just math on the bits.
 
 ## Install & usage
 
-There is nothing to install beyond Node (uses only built-in `assert` for
-tests). Once vendored/published under its final name you would:
+Zero runtime dependencies (tests use only built-in `assert`) — you can also
+vendor the folder directly. In your project:
 
 ```js
-const ip = require('ip-cidr'); // during development: require('./index.js')
+const ip = require('@verifyhash/ip-cidr'); // during development: require('./index.js')
 
 // Containment
 ip.contains('10.0.0.0/8', '10.1.2.3');      // => true
@@ -140,4 +145,4 @@ validate/parse/contain paths.
 
 ## License
 
-MIT — see `LICENSE` (owner name is a placeholder until graduation).
+MIT — see `LICENSE`.

package/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Type declarations for @verifyhash/ip-cidr — zero-dependency IPv4 (+ basic
+ * IPv6) address/CIDR toolkit.
+ *
+ * IPv4 is fully supported (CIDR math, ip<->integer, containment); IPv6 is
+ * limited to validate/parse and containment, using BigInt so no precision is
+ * lost. No broadcast/first/last helpers for v6 ("broadcast" is not an IPv6
+ * concept).
+ */
+
+/**
+ * Validate a dotted-quad IPv4 string (four octets 0-255, no leading zeros).
+ * Returns true/false, never throws.
+ */
+export function isValidIPv4(str: string): boolean;
+
+/**
+ * Convert a valid IPv4 string to its unsigned 32-bit integer value
+ * (0 .. 4294967295). Throws on invalid input.
+ */
+export function ipv4ToInt(str: string): number;
+
+/**
+ * Convert an unsigned 32-bit integer to a dotted-quad IPv4 string. Throws on
+ * out-of-range / non-integer input.
+ */
+export function intToIpv4(int: number): string;
+
+/**
+ * Validate an IPv6 string (supports "::" compression and an embedded IPv4
+ * tail; zone ids like "%eth0" are rejected). Returns true/false, never throws.
+ */
+export function isValidIPv6(str: string): boolean;
+
+/** Convert an IPv6 string to a BigInt (0 .. 2**128-1). Throws on invalid input. */
+export function ipv6ToBigInt(str: string): bigint;
+
+/**
+ * Convert a BigInt (0 .. 2**128-1) to a fully-expanded (uncompressed) IPv6
+ * string. Throws on out-of-range input.
+ */
+export function bigIntToIpv6(value: bigint): string;
+
+/** 4 for a valid IPv4 address, 6 for a valid IPv6 address, else null. Never throws. */
+export function ipVersion(str: string): 4 | 6 | null;
+
+/** Descriptor returned by parse() for an IPv4 address. */
+export interface ParsedIPv4 {
+  version: 4;
+  address: string;
+  /** Unsigned 32-bit integer value of the address. */
+  int: number;
+}
+
+/** Descriptor returned by parse() for an IPv6 address. */
+export interface ParsedIPv6 {
+  version: 6;
+  address: string;
+  /** BigInt value of the address. */
+  big: bigint;
+}
+
+/** Parse any IPv4 or IPv6 address into a descriptor object, or throw. */
+export function parse(str: string): ParsedIPv4 | ParsedIPv6;
+
+/** Descriptor returned by parseCidr() for an IPv4 block. */
+export interface Cidr4 {
+  version: 4;
+  /** Normalised CIDR, e.g. '10.0.0.0/24'. */
+  cidr: string;
+  prefix: number;
+  network: string;
+  networkInt: number;
+  broadcast: string;
+  broadcastInt: number;
+  firstHost: string;
+  firstHostInt: number;
+  lastHost: string;
+  lastHostInt: number;
+  /** Total addresses in the block. */
+  size: number;
+  /** Usable host count (/31 and /32 count every address, per RFC 3021). */
+  hostCount: number;
+}
+
+/** Descriptor returned by parseCidr() for an IPv6 block (no broadcast in v6). */
+export interface Cidr6 {
+  version: 6;
+  /** Normalised CIDR with a fully-expanded network address. */
+  cidr: string;
+  prefix: number;
+  network: string;
+  networkBig: bigint;
+  firstHost: string;
+  firstHostBig: bigint;
+  lastHost: string;
+  lastHostBig: bigint;
+  /** Total addresses in the block (BigInt). */
+  size: bigint;
+  /** Same as size — IPv6 has no broadcast reservation. */
+  hostCount: bigint;
+}
+
+/** Parse a CIDR string ("10.0.0.0/24" or "2001:db8::/32"), or throw. */
+export function parseCidr(str: string): Cidr4 | Cidr6;
+
+/**
+ * Does the CIDR block contain the given IP? Cross-family never matches
+ * (returns false). Throws only if either argument is not parseable.
+ */
+export function contains(cidr: string, ip: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verifyhash/ip-cidr",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Zero-dependency IPv4 (and basic IPv6) address/CIDR toolkit for Node.js: validate/parse, CIDR math (network, broadcast, first/last host, host count), ip<->integer, and containment.",
   "keywords": [
     "ip",
@@ -15,6 +15,7 @@
     "ip-to-int"
   ],
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "node test/index.test.js"
   },
@@ -22,7 +23,8 @@
   "files": [
     "index.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"