breaking: change expandCidr to a generator

Fixes: #22

README.md

@@ -7,13 +7,26 @@
 ```js
 import {mergeCidr, excludeCidr, expandCidr, overlapCidr, containsCidr, normalizeCidr, parseCidr} from "cidr-tools";
 
-mergeCidr(["1.0.0.0/24", "1.0.1.0/24"]); //=> ["1.0.0.0/23"]
-excludeCidr(["::1/127"], "::1/128") //=> ["::/128"]
-expandCidr(["2001:db8::/126"]) //=> ["2001:db8::", "2001:db8::1", "2001:db8::2", "2001:db8::3"]
-overlapCidr("1.0.0.0/24", "1.0.0.128/25") //=> true
-containsCidr(["1.0.0.0/24", "2.0.0.0/24"], "1.0.0.1") //=> true
-normalizeCidr("::ffff/64") //=> "::/64"
-parseCidr("::/64"); // => {cidr: "::/64", version: 6, prefix: "64", start: 0n, end: 18446744073709551615n}
+mergeCidr(["1.0.0.0/24", "1.0.1.0/24"]);
+//=> ["1.0.0.0/23"]
+
+excludeCidr(["::1/127"], "::1/128");
+//=> ["::/128"]
+
+Array.from(expandCidr(["2001:db8::/126"]));
+//=> ["2001:db8::", "2001:db8::1", "2001:db8::2", "2001:db8::3"]
+
+overlapCidr("1.0.0.0/24", "1.0.0.128/25");
+//=> true
+
+containsCidr(["1.0.0.0/24", "2.0.0.0/24"], "1.0.0.1");
+//=> true
+
+normalizeCidr("::ffff/64");
+//=> "::/64"
+
+parseCidr("::/64");
+// => {cidr: "::/64", version: 6, prefix: "64", start: 0n, end: 18446744073709551615n}
 ```
 
 ## API
@@ -41,7 +54,7 @@ Returns an array of merged remaining networks.
 
 - `networks` *String* or *Array*: One or more CIDR or IP addresses.
 
-Returns an array of individual IPs contained in the networks.
+Returns a generator for individual IPs contained in the networks. Be aware that asking for expansions of big networks can result in long runtimes and possibly high memory usage. One million IPs takes about 2 seconds on modern hardware.
 
 ### overlapCidr(networksA, networksB)
 

index.test.ts

@@ -50,10 +50,10 @@ test("excludeCidr", () => {
 });
 
 test("expandCidr", () => {
-  expect(expandCidr(["1.2.3.0/31"])).toEqual(["1.2.3.0", "1.2.3.1"]);
-  expect(expandCidr(["1::/126"])).toEqual(["1::", "1::1", "1::2", "1::3"]);
-  expect(expandCidr(["2008:db1::/127"])).toEqual(["2008:db1::", "2008:db1::1"]);
-  expect(expandCidr("2008:db1::/127")).toEqual(["2008:db1::", "2008:db1::1"]);
+  expect(Array.from(expandCidr(["1.2.3.0/31"]))).toEqual(["1.2.3.0", "1.2.3.1"]);
+  expect(Array.from(expandCidr(["1::/126"]))).toEqual(["1::", "1::1", "1::2", "1::3"]);
+  expect(Array.from(expandCidr(["2008:db1::/127"]))).toEqual(["2008:db1::", "2008:db1::1"]);
+  expect(Array.from(expandCidr("2008:db1::/127"))).toEqual(["2008:db1::", "2008:db1::1"]);
 });
 
 test("overlapCidr", () => {

index.ts

@@ -382,17 +382,15 @@ export function excludeCidr(base: Networks, excl: Networks): Network[] {
   return bases[4].concat(bases[6]).sort(compare);
 }
 
-export function expandCidr(nets: Networks): Network[] {
+export function* expandCidr(nets: Networks): Generator<Network> {
   const arr: Network[] = uniq(Array.isArray(nets) ? nets : [nets]);
-  const ips: Network[] = [];
 
   for (const net of mergeCidr(arr)) {
     const {start, end, version} = parseCidr(net);
     for (let number = start; number <= end; number++) {
-      ips.push(stringifyIp({number, version}));
+      yield normalizeCidr(stringifyIp({number, version}));
     }
   }
-  return ips.map(ip => normalizeCidr(ip));
 }
 
 export function overlapCidr(a: Networks, b: Networks): boolean {