@lakutata/netif 0.0.0-stage → 3.1.5

package/dist/cjs/lib/NetworkInterface.js

@@ -0,0 +1,391 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkInterface = void 0;
+exports.changesOf = changesOf;
+const node_events_1 = require("node:events");
+const NetIfException_js_1 = require("../exceptions/NetIfException.js");
+const NetIfNotEnforcedException_js_1 = require("../exceptions/NetIfNotEnforcedException.js");
+const NetIfNotFoundException_js_1 = require("../exceptions/NetIfNotFoundException.js");
+const NetIfNotSupportedException_js_1 = require("../exceptions/NetIfNotSupportedException.js");
+const NetIfTimeoutException_js_1 = require("../exceptions/NetIfTimeoutException.js");
+const Enforcement_js_1 = require("./Enforcement.js");
+const InterfaceListener_js_1 = require("./InterfaceListener.js");
+const InterfaceUDPSocket_js_1 = require("./InterfaceUDPSocket.js");
+const Internal_js_1 = require("./Internal.js");
+const Native_js_1 = require("./Native.js");
+const Registry_js_1 = require("./Registry.js");
+const Snapshot_js_1 = require("./Snapshot.js");
+const MAC = /^[0-9a-f]{2}([:-][0-9a-f]{2}){5}$/i;
+/**
+ * The key of an address in a comparison
+ */
+function keyOf(address) {
+    return `${address.family}|${address.address}|${address.scopeid ?? ''}`;
+}
+/**
+ * What changed between two states of an interface: whether it appeared or disappeared, its link came up or went down,
+ * and its addresses added and removed
+ */
+function changesOf(previous, next) {
+    const before = new Map((previous?.addresses ?? []).map((address) => [keyOf(address), address]));
+    const after = new Map((next?.addresses ?? []).map((address) => [keyOf(address), address]));
+    const wasRunning = previous?.running ?? false;
+    const isRunning = next?.running ?? false;
+    return {
+        appeared: !previous && !!next,
+        disappeared: !!previous && !next,
+        up: !wasRunning && isRunning,
+        down: wasRunning && !isRunning,
+        added: [...after].filter(([key]) => !before.has(key)).map(([, address]) => ({ ...address })),
+        removed: [...before].filter(([key]) => !after.has(key)).map(([, address]) => ({ ...address }))
+    };
+}
+/**
+ * A network interface of the machine, followed: its state and addresses now, events when they change, and the servers
+ * listening on it. The interface may not exist yet (a USB adapter not plugged in, a system starting): the object follows
+ * it once it appears, and again when it is unplugged and plugged back.
+ * @example
+ * ```typescript
+ * import {type InterfaceAddress, NetworkInterface} from '@lakutata/netif'
+ *
+ * const management: NetworkInterface = new NetworkInterface('eth1')
+ * console.log(management.present, management.running, management.addresses.map(address => address.address))
+ * management.on('change', ({added, removed}) => console.log('added', added, 'removed', removed))
+ * management.on('down', () => console.log('the cable of eth1 is unplugged'))
+ * const address: InterfaceAddress = await management.waitForAddress({family: 'IPv4', timeout: 30000})
+ * console.log(`http://${address.address}:8080`)
+ * management.close()
+ * ```
+ */
+class NetworkInterface extends node_events_1.EventEmitter {
+    #state;
+    #unsubscribe;
+    #waits = new Set();
+    #observers = new Set();
+    /**
+     * Follows an interface.
+     * @param selector Its name, `{mac}` or `{index}`.
+     * @throws NetIfNotFoundException An index that no interface has (an index is never given again once its interface is
+     * gone), or a hardware address that several interfaces have now (a bridge and its ports: give the name then).
+     */
+    constructor(selector) {
+        super();
+        this.selector = NetworkInterface.#normalized(selector);
+        this.#unsubscribe = Registry_js_1.registry.subscribe((interfaces) => this.#update(interfaces));
+        const { entry, ambiguous } = this.#match(Registry_js_1.registry.current());
+        if (ambiguous || (!entry && typeof this.selector === 'object' && 'index' in this.selector)) {
+            this.close();
+            throw new NetIfNotFoundException_js_1.NetIfNotFoundException(ambiguous
+                ? `Several interfaces have the hardware address ${this.selector.mac}: give the interface by its name`
+                : `No interface has the index ${this.selector.index}`);
+        }
+        this.#state = entry;
+    }
+    /**
+     * The network interfaces of the machine, as `listInterfaces()` gives them.
+     * @returns The interfaces, in the order of the system.
+     * @example
+     * ```typescript
+     * import {NetworkInterface} from '@lakutata/netif'
+     *
+     * const names: string[] = NetworkInterface.list().map(entry => entry.name)
+     * ```
+     */
+    static list() {
+        return (0, Snapshot_js_1.readInterfaces)().interfaces;
+    }
+    static #normalized(selector) {
+        if (typeof selector === 'string') {
+            if (!selector)
+                throw new TypeError('The name of an interface is empty');
+            return selector;
+        }
+        if (selector && typeof selector === 'object' && 'mac' in selector) {
+            if (typeof selector.mac !== 'string' || !MAC.test(selector.mac))
+                throw new TypeError(`${String(selector.mac)} is not a hardware address (aa:bb:cc:dd:ee:ff)`);
+            return { mac: selector.mac.toLowerCase().replaceAll('-', ':') };
+        }
+        if (selector && typeof selector === 'object' && 'index' in selector) {
+            if (!Number.isInteger(selector.index) || selector.index <= 0)
+                throw new TypeError(`${String(selector.index)} is not the index of an interface`);
+            return { index: selector.index };
+        }
+        throw new TypeError('An interface is given by its name, {mac} or {index}');
+    }
+    /**
+     * Whether the interface exists now.
+     */
+    get present() {
+        return !!this.#state;
+    }
+    /**
+     * Its name, `undefined` while it does not exist.
+     */
+    get name() {
+        return this.#state?.name;
+    }
+    /**
+     * Its index, `undefined` while it does not exist. It changes when the interface is unplugged and plugged again.
+     */
+    get index() {
+        return this.#state?.index;
+    }
+    /**
+     * Its hardware address, `undefined` while it does not exist or when it has none (and on the macOS versions that hide
+     * it).
+     */
+    get mac() {
+        return this.#state?.mac;
+    }
+    /**
+     * Whether it is enabled (its administrative state); `false` while it does not exist.
+     */
+    get up() {
+        return this.#state?.up ?? false;
+    }
+    /**
+     * Whether its link is up (a cable plugged in, an association made); `false` while it does not exist.
+     */
+    get running() {
+        return this.#state?.running ?? false;
+    }
+    /**
+     * Whether it is the loopback interface.
+     */
+    get loopback() {
+        return this.#state?.loopback ?? false;
+    }
+    /**
+     * Its usable addresses now, an empty array when it has none or does not exist.
+     */
+    get addresses() {
+        return this.#state ? this.#state.addresses.map((address) => ({ ...address })) : [];
+    }
+    /**
+     * Its state now as `listInterfaces()` gives it, `undefined` while it does not exist.
+     */
+    get info() {
+        return this.#state ? { ...this.#state, addresses: this.addresses } : undefined;
+    }
+    /**
+     * Whether the object was closed.
+     */
+    get closed() {
+        return !this.#unsubscribe;
+    }
+    /**
+     * An address of the interface: one it has now, or the first one it gets.
+     * @param options The family of the address and the milliseconds to wait at most.
+     * @returns The address.
+     * @throws NetIfTimeoutException No address came in time.
+     * @throws NetIfException The object was closed while waiting.
+     * @example
+     * ```typescript
+     * import {type InterfaceAddress, NetworkInterface} from '@lakutata/netif'
+     *
+     * const wan: NetworkInterface = new NetworkInterface('eth0')
+     * const address: InterfaceAddress = await wan.waitForAddress({family: 'IPv4', timeout: 60000})
+     * wan.close()
+     * ```
+     */
+    waitForAddress(options = {}) {
+        const pick = () => this.addresses.find((address) => !options.family || address.family === options.family);
+        const found = pick();
+        if (found)
+            return Promise.resolve(found);
+        if (this.closed)
+            return Promise.reject(new NetIfException_js_1.NetIfException('The NetworkInterface is closed'));
+        return new Promise((resolve, reject) => {
+            //The wait keeps the process alive, as a server waiting for connections does
+            const alive = setInterval(() => undefined, 0x7fffffff);
+            let timer;
+            const finish = () => {
+                clearInterval(alive);
+                clearTimeout(timer);
+                this.off('change', changed);
+                this.#waits.delete(closed);
+            };
+            const changed = () => {
+                const address = pick();
+                if (!address)
+                    return;
+                finish();
+                resolve(address);
+            };
+            const closed = (error) => {
+                finish();
+                reject(error);
+            };
+            this.on('change', changed);
+            this.#waits.add(closed);
+            if (options.timeout !== undefined) {
+                timer = setTimeout(() => closed(new NetIfTimeoutException_js_1.NetIfTimeoutException(`${this.#described()} got no ${options.family ?? ''} address in ${options.timeout} ms`.replace('  ', ' '))), options.timeout);
+            }
+        });
+    }
+    /**
+     * Listens on the interface for the server: its connections are accepted by the listener returned and given to the
+     * server, which handles them as its own. On Linux the sockets are bound to the interface (whatever its addresses, the
+     * system refuses the connections coming through another interface); on Windows and macOS each address of the
+     * interface is listened on, and listened on again when they change (`enforced` tells whether the system refuses the
+     * connections coming through another interface). The interface may not exist yet, nor have an address: it is listened
+     * on once it can be, and again when it is unplugged and plugged back.
+     * @param server A `net.Server` or a server built on one: `http`, `https`, `http2`, `tls`; for Express
+     * `createServer(app)`, for Fastify `fastify.server`. The server itself must not listen.
+     * @param options The port, the families, `strict` and the backlog.
+     * @returns The listener, once the interface is listened on (or waited for).
+     * @throws NetIfNotEnforcedException With `strict`, where the system cannot refuse the connections coming through
+     * another interface.
+     * @throws NetIfException The system refused the first listening, its code as `errno` (`'EADDRINUSE'`, `'EACCES'`…).
+     * Later refusals are `error` events of the listener, and retried.
+     * @example
+     * ```typescript
+     * import {createServer} from 'node:http'
+     * import express from 'express'
+     * import {type InterfaceListener, NetworkInterface} from '@lakutata/netif'
+     *
+     * const app = express()
+     * app.get('/', (request, response) => response.send('ok'))
+     * const management: NetworkInterface = new NetworkInterface({mac: '52:54:00:12:34:56'})
+     * const listener: InterfaceListener = await management.listen(createServer(app), {port: 8080})
+     * listener.on('error', error => console.error(error))
+     * ```
+     */
+    async listen(server, options) {
+        if (this.closed)
+            throw new NetIfException_js_1.NetIfException('The NetworkInterface is closed');
+        return new InterfaceListener_js_1.InterfaceListener(this, server, options).start();
+    }
+    /**
+     * A UDP socket of the interface, with the methods and the events of a `dgram` socket. On Linux it is bound to the
+     * interface: it receives what comes through it, broadcasts and the multicast of the groups joined there included,
+     * whatever its addresses. On Windows and macOS a socket is bound to each address of the interface (on macOS it
+     * receives no broadcast nor multicast then). It is bound again when the addresses change and when the interface is
+     * plugged back.
+     * @param options The port, the families and `strict`.
+     * @returns The socket, once it is bound (or the interface waited for).
+     * @throws NetIfNotEnforcedException With `strict`, where the system cannot refuse the datagrams coming through
+     * another interface.
+     * @throws NetIfException The system refused the first binding, its code as `errno`.
+     * @example
+     * ```typescript
+     * import {type InterfaceUDPSocket, NetworkInterface} from '@lakutata/netif'
+     *
+     * const socket: InterfaceUDPSocket = await new NetworkInterface('eth1').createUDPSocket({port: 9999, family: 'IPv4'})
+     * socket.setBroadcast(true)
+     * socket.on('message', (message, remote) => socket.send(message, remote.port, remote.address))
+     * ```
+     */
+    async createUDPSocket(options) {
+        if (this.closed)
+            throw new NetIfException_js_1.NetIfException('The NetworkInterface is closed');
+        return new InterfaceUDPSocket_js_1.InterfaceUDPSocket(this, options).start();
+    }
+    /**
+     * A socket bound to the interface (Linux, `SO_BINDTODEVICE`), on the port of every address of its family: it gets the
+     * connections and the datagrams that come through the interface, whatever the address they were sent to, and the
+     * system refuses the other ones. For the users that need the server itself listening (its `address()` and `close()`
+     * as usual): the socket is not made again when the interface is unplugged and plugged back, which `listen()` does.
+     * In Bun, give the descriptor to a `net.Server` or a `dgram` socket (Bun's `http.Server` does not listen on one).
+     * @param options The port, the family, the type and the backlog.
+     * @returns The descriptor of the socket and its port.
+     * @throws NetIfNotSupportedException Outside Linux: macOS and Windows have no socket bound to an interface.
+     * @throws NetIfNotFoundException The interface does not exist now.
+     * @throws NetIfNotEnforcedException The process may not bind a socket to an interface (CAP_NET_RAW before Linux 5.7).
+     * @throws NetIfException Another refusal of the system, its code as `errno` (`'EADDRINUSE'`…).
+     * @example
+     * ```typescript
+     * import {createServer} from 'node:http'
+     * import {type BoundSocket, NetworkInterface} from '@lakutata/netif'
+     *
+     * const management: NetworkInterface = new NetworkInterface('eth1')
+     * const socket: BoundSocket = management.bindSocket({port: 8080, family: 'IPv4', type: 'tcp'})
+     * createServer((request, response) => response.end('ok')).listen({fd: socket.fd})
+     * ```
+     */
+    bindSocket(options = {}) {
+        const family = options.family ?? 'IPv4';
+        const type = options.type ?? 'tcp';
+        if (process.platform !== 'linux')
+            throw new NetIfNotSupportedException_js_1.NetIfNotSupportedException(`${process.platform === 'darwin' ? 'macOS' : process.platform === 'win32' ? 'Windows' : process.platform} has no socket bound to an interface: bindSocket() is for Linux; listen() and createUDPSocket() work everywhere`);
+        if (!this.#state)
+            throw new NetIfNotFoundException_js_1.NetIfNotFoundException(`${this.#described()} does not exist now`);
+        try {
+            const bound = (0, Native_js_1.nativeBindSocket)(this.#state.name, family === 'IPv4' ? 4 : 6, type === 'tcp', options.port ?? 0, options.backlog ?? 511);
+            return { fd: bound.fd, port: bound.port, family: family, type: type };
+        }
+        catch (error) {
+            if (error instanceof NetIfException_js_1.NetIfException && (error.errno === 'EPERM' || error.errno === 'EACCES') && /SO_BINDTODEVICE/.test(error.message)) {
+                throw new NetIfNotEnforcedException_js_1.NetIfNotEnforcedException(`The process may not bind a socket to ${this.#state.name}. ${Enforcement_js_1.LINUX_PERMISSION}`, { cause: error });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Stops following the interface: no event any more; its listeners are closed, the waits of `waitForAddress()`
+     * rejected.
+     */
+    close() {
+        if (!this.#unsubscribe)
+            return;
+        this.#unsubscribe();
+        this.#unsubscribe = undefined;
+        for (const closed of [...this.#waits])
+            closed(new NetIfException_js_1.NetIfException('The NetworkInterface was closed while waiting for an address'));
+        for (const observer of [...this.#observers])
+            observer('close');
+        this.#observers.clear();
+    }
+    /**
+     * Internal: follows the readings of the interfaces (the listeners of the interface)
+     */
+    [Internal_js_1.OBSERVE](observer) {
+        this.#observers.add(observer);
+        return () => {
+            this.#observers.delete(observer);
+        };
+    }
+    #described() {
+        if (typeof this.selector === 'string')
+            return `The interface ${this.selector}`;
+        return 'mac' in this.selector ? `The interface of ${this.selector.mac}` : `The interface of index ${this.selector.index}`;
+    }
+    /**
+     * The interface given among the interfaces, and whether several match (a hardware address shared)
+     */
+    #match(interfaces) {
+        const selector = this.selector;
+        const matches = interfaces.filter((entry) => {
+            if (typeof selector === 'string')
+                return entry.name === selector;
+            if ('mac' in selector)
+                return entry.mac === selector.mac;
+            return entry.index === selector.index;
+        });
+        return { entry: matches.length === 1 ? matches[0] : undefined, ambiguous: matches.length > 1 };
+    }
+    /**
+     * The interfaces read again: the state updated, the events of what changed emitted
+     */
+    #update(interfaces) {
+        if (this.closed)
+            return;
+        const previous = this.#state;
+        const next = this.#match(interfaces).entry;
+        this.#state = next;
+        const changes = changesOf(previous, next);
+        if (changes.appeared)
+            this.emit('added');
+        if (changes.up)
+            this.emit('up');
+        if (changes.down)
+            this.emit('down');
+        if (changes.added.length || changes.removed.length)
+            this.emit('change', { addresses: this.addresses, added: changes.added, removed: changes.removed });
+        if (changes.disappeared)
+            this.emit('removed');
+        for (const observer of [...this.#observers])
+            observer('update');
+    }
+}
+exports.NetworkInterface = NetworkInterface;

package/dist/cjs/lib/Registry.d.ts

@@ -0,0 +1,26 @@
+import { type NetworkInterfaceInfo } from './Types.js';
+/**
+ * A subscriber of the changes: called with the interfaces read after each change
+ */
+export type Subscriber = (interfaces: NetworkInterfaceInfo[]) => void;
+/**
+ * The interfaces of the machine as the package follows them: the notifications of the system shared by every
+ * subscriber of the thread, started with the first one and stopped with the last one. The timers do not keep the event
+ * loop alive.
+ */
+declare class Registry {
+    #private;
+    /**
+     * The interfaces read last while followed, read now otherwise
+     */
+    current(): NetworkInterfaceInfo[];
+    /**
+     * Follows the interfaces: the subscriber is called after each change; the function returned unsubscribes it
+     */
+    subscribe(subscriber: Subscriber): () => void;
+}
+/**
+ * The registry of the thread
+ */
+export declare const registry: Registry;
+export {};

package/dist/cjs/lib/Registry.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registry = void 0;
+const Native_js_1 = require("./Native.js");
+const Snapshot_js_1 = require("./Snapshot.js");
+//The notifications of the system come in bursts (an interface plugged: its link, then each address): read once after
+const SETTLE = 50;
+//An IPv6 address in its duplicate address detection: read again until it is usable (no notification of it on macOS)
+const TENTATIVE_INTERVAL = 300;
+const TENTATIVE_LIMIT = 15000;
+/**
+ * The interfaces of the machine as the package follows them: the notifications of the system shared by every
+ * subscriber of the thread, started with the first one and stopped with the last one. The timers do not keep the event
+ * loop alive.
+ */
+class Registry {
+    #subscribers = new Set();
+    #interfaces = [];
+    #settle;
+    #tentative;
+    #tentativeSince = 0;
+    /**
+     * The interfaces read last while followed, read now otherwise
+     */
+    current() {
+        return this.#subscribers.size ? this.#interfaces : (0, Snapshot_js_1.readInterfaces)().interfaces;
+    }
+    /**
+     * Follows the interfaces: the subscriber is called after each change; the function returned unsubscribes it
+     */
+    subscribe(subscriber) {
+        if (!this.#subscribers.size) {
+            this.#tentativeSince = Date.now();
+            this.#interfaces = this.#read();
+            (0, Native_js_1.nativeWatch)(() => this.#changed());
+        }
+        this.#subscribers.add(subscriber);
+        return () => this.#unsubscribe(subscriber);
+    }
+    #unsubscribe(subscriber) {
+        if (!this.#subscribers.delete(subscriber) || this.#subscribers.size)
+            return;
+        (0, Native_js_1.nativeUnwatch)();
+        clearTimeout(this.#settle);
+        clearTimeout(this.#tentative);
+        this.#settle = undefined;
+        this.#tentative = undefined;
+    }
+    /**
+     * A notification of the system: the interfaces read once the burst has settled
+     */
+    #changed() {
+        if (this.#settle || !this.#subscribers.size)
+            return;
+        this.#settle = setTimeout(() => {
+            this.#settle = undefined;
+            this.#tentativeSince = Date.now();
+            this.#refresh();
+        }, SETTLE);
+        this.#settle.unref();
+    }
+    #refresh() {
+        if (!this.#subscribers.size)
+            return;
+        try {
+            this.#interfaces = this.#read();
+        }
+        catch {
+            //The system cannot be read now: the next notification reads it again
+            return;
+        }
+        for (const subscriber of [...this.#subscribers]) {
+            try {
+                subscriber(this.#interfaces);
+            }
+            catch (error) {
+                queueMicrotask(() => {
+                    throw error;
+                });
+            }
+        }
+    }
+    /**
+     * The interfaces now; while an address is tentative, read again a little later
+     */
+    #read() {
+        const { interfaces, tentative } = (0, Snapshot_js_1.readInterfaces)();
+        clearTimeout(this.#tentative);
+        this.#tentative = undefined;
+        if (tentative && Date.now() - this.#tentativeSince < TENTATIVE_LIMIT) {
+            this.#tentative = setTimeout(() => {
+                this.#tentative = undefined;
+                this.#refresh();
+            }, TENTATIVE_INTERVAL);
+            this.#tentative.unref();
+        }
+        return interfaces;
+    }
+}
+/**
+ * The registry of the thread
+ */
+exports.registry = new Registry();

package/dist/cjs/lib/Snapshot.d.ts

@@ -0,0 +1,17 @@
+import { type NativeInterface } from './Native.js';
+import { type NetworkInterfaceInfo } from './Types.js';
+/**
+ * The mask of a prefix length: `'255.255.255.0'` for 24 in IPv4, `'ffff:ffff:ffff:ffff::'` for 64 in IPv6
+ */
+export declare function netmaskOf(family: 'IPv4' | 'IPv6', prefixLength: number): string;
+/**
+ * An interface read by the addon as an interface of the package: its usable addresses only
+ */
+export declare function interfaceOf(entry: NativeInterface): NetworkInterfaceInfo;
+/**
+ * The interfaces of the machine now, and whether some address is still tentative (to be read again soon)
+ */
+export declare function readInterfaces(): {
+    interfaces: NetworkInterfaceInfo[];
+    tentative: boolean;
+};

package/dist/cjs/lib/Snapshot.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.netmaskOf = netmaskOf;
+exports.interfaceOf = interfaceOf;
+exports.readInterfaces = readInterfaces;
+const Native_js_1 = require("./Native.js");
+/**
+ * The mask of a prefix length: `'255.255.255.0'` for 24 in IPv4, `'ffff:ffff:ffff:ffff::'` for 64 in IPv6
+ */
+function netmaskOf(family, prefixLength) {
+    const bits = family === 'IPv4' ? 32 : 128;
+    const length = Math.max(0, Math.min(bits, prefixLength));
+    const bytes = [];
+    for (let index = 0; index < bits / 8; index++) {
+        const taken = Math.max(0, Math.min(8, length - index * 8));
+        bytes.push(taken === 0 ? 0 : (0xff << (8 - taken)) & 0xff);
+    }
+    if (family === 'IPv4')
+        return bytes.join('.');
+    const groups = [];
+    for (let index = 0; index < 16; index += 2)
+        groups.push(bytes[index] * 256 + bytes[index + 1]);
+    //The longest run of zero groups (two at least) written ::
+    let start = -1;
+    let size = 0;
+    for (let index = 0; index < 8;) {
+        if (groups[index] !== 0) {
+            index++;
+            continue;
+        }
+        let end = index;
+        while (end < 8 && groups[end] === 0)
+            end++;
+        if (end - index > size) {
+            start = index;
+            size = end - index;
+        }
+        index = end;
+    }
+    const hex = groups.map((group) => group.toString(16));
+    if (size < 2)
+        return hex.join(':');
+    return `${hex.slice(0, start).join(':')}::${hex.slice(start + size).join(':')}`;
+}
+/**
+ * An address read by the addon as an address of the package
+ */
+function addressOf(address) {
+    const converted = {
+        address: address.address,
+        family: address.family,
+        netmask: netmaskOf(address.family, address.prefixLength),
+        cidr: `${address.address}/${address.prefixLength}`
+    };
+    if (address.family === 'IPv6')
+        converted.scopeid = address.scopeid ?? 0;
+    return converted;
+}
+/**
+ * An interface read by the addon as an interface of the package: its usable addresses only
+ */
+function interfaceOf(entry) {
+    const converted = {
+        name: entry.name,
+        index: entry.index,
+        up: entry.up,
+        running: entry.running,
+        loopback: entry.loopback,
+        addresses: entry.addresses.filter((address) => !address.tentative).map(addressOf)
+    };
+    if (entry.mac)
+        converted.mac = entry.mac;
+    return converted;
+}
+/**
+ * The interfaces of the machine now, and whether some address is still tentative (to be read again soon)
+ */
+function readInterfaces() {
+    const entries = (0, Native_js_1.nativeList)();
+    return {
+        interfaces: entries.map(interfaceOf),
+        tentative: entries.some((entry) => entry.addresses.some((address) => address.tentative))
+    };
+}

package/dist/cjs/lib/Types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * An address of a network interface, written as `os.networkInterfaces()` writes it
+ */
+export interface InterfaceAddress {
+    /**
+     * The address: `'192.168.10.2'`, `'fd00::2'`, `'fe80::1c82:430f:35a3:800a'` (an IPv6 address without its scope).
+     */
+    address: string;
+    /**
+     * `'IPv4'` or `'IPv6'`.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * The mask of the network of the address: `'255.255.255.0'`, `'ffff:ffff:ffff:ffff::'`.
+     */
+    netmask: string;
+    /**
+     * The address and the length of its prefix: `'192.168.10.2/24'`.
+     */
+    cidr: string;
+    /**
+     * IPv6 only: the scope of the address, as `os.networkInterfaces()` gives it: the index of the interface for a
+     * link-local address (`fe80::…`, written `fe80::…%<scopeid>` to be connected to), `0` for a global one (Windows gives
+     * a site-local address, `fec0::…`, the number of its site).
+     */
+    scopeid?: number;
+}
+/**
+ * A network interface of the machine and its state when it was read
+ */
+export interface NetworkInterfaceInfo {
+    /**
+     * The name of the interface: `'eth1'`, `'en0'`, on Windows the name of its network connection (`'以太网 2'`,
+     * `'Ethernet 2'`, in the language of the system).
+     */
+    name: string;
+    /**
+     * The index the system gives the interface. It changes when the interface is unplugged and plugged again.
+     */
+    index: number;
+    /**
+     * The hardware address (`'52:54:00:12:34:56'`), `undefined` for an interface without one (loopback, tunnels) and on
+     * the macOS versions that hide it from the processes (macOS 27 gives `02:00:00:00:00:00` for every interface).
+     */
+    mac?: string;
+    /**
+     * Whether the interface is enabled (its administrative state). On Windows a disabled adapter is not listed at all.
+     */
+    up: boolean;
+    /**
+     * Whether its link is up: a cable plugged in, an association made.
+     */
+    running: boolean;
+    /**
+     * Whether it is the loopback interface.
+     */
+    loopback: boolean;
+    /**
+     * Its usable addresses, an empty array when it has none. An IPv6 address still in its duplicate address detection
+     * (about one second after it is added) is not usable yet and not listed.
+     */
+    addresses: InterfaceAddress[];
+}