links-notation 0.26.0 → 0.27.1

package/README.md

@@ -27,6 +27,14 @@ bun add links-notation
 import { Parser, Link } from 'npm:links-notation@^0.6.0';
 ```
 
+#### In browsers
+
+The package has no runtime dependencies and imports no Node.js built-in
+modules, so bundlers need no polyfills. For example, esbuild bundles it with
+`esbuild entry.js --bundle --platform=browser`. Before 0.27.1, `StreamParser`
+imported Node's `events` module, and browser bundles needed the `events`
+package installed as a polyfill.
+
 ### Local Development Setup
 
 For contributors working on the source code:
@@ -443,7 +451,11 @@ Container for grouping related links.
 
 #### `StreamParser`
 
-EventEmitter-based streaming parser for incremental parsing.
+Event-emitting streaming parser for incremental parsing. Its built-in emitter
+has the Node.js `EventEmitter` listener methods (`on`, `once`, `off`,
+`addListener`, `removeListener`, `prependListener`, `prependOnceListener`,
+`removeAllListeners`, `emit`, `listeners`, `listenerCount`, `eventNames`) and
+works in browsers without a polyfill. It is not an `instanceof EventEmitter`.
 
 - `constructor(options)` - Create a new streaming parser
   - `options.maxInputSize` - Maximum input size in bytes (default: 10MB)

package/README.ru.md

@@ -174,6 +174,13 @@ stream.end('следующая связь');
 `drain()`, `reset()` и ограничение размера незавершённой записи. См.
 [исполняемый пример](../examples/js_streaming_parser.js).
 
+Пакет не импортирует встроенные модули Node.js, поэтому сборщикам для браузера
+не нужны полифилы: например, `esbuild entry.js --bundle --platform=browser`.
+Встроенный в `StreamParser` эмиттер поддерживает методы подписки
+`EventEmitter` из Node.js (`on`, `once`, `off`, `removeListener`, `emit`,
+`listenerCount` и другие). До версии 0.27.1 `StreamParser` импортировал модуль
+`events`, и для браузерной сборки требовался пакет-полифил `events`.
+
 ## Примеры синтаксиса
 
 ### Дуплеты (2-кортежи)

package/dist/index.js

@@ -3072,8 +3072,104 @@ function formatIndentedDocument(entries) {
 `) + `
 ` : "";
 }
+// src/Emitter.js
+class Emitter {
+  #listeners = new Map;
+  on(event, listener) {
+    return this.#add(event, listener, false, false);
+  }
+  addListener(event, listener) {
+    return this.on(event, listener);
+  }
+  prependListener(event, listener) {
+    return this.#add(event, listener, false, true);
+  }
+  once(event, listener) {
+    return this.#add(event, listener, true, false);
+  }
+  prependOnceListener(event, listener) {
+    return this.#add(event, listener, true, true);
+  }
+  off(event, listener) {
+    checkListener(listener);
+    const entries = this.#listeners.get(event);
+    if (!entries)
+      return this;
+    const entry = entries.findLast((entry) => entry.listener === listener);
+    if (entry)
+      this.#remove(event, entry);
+    return this;
+  }
+  removeListener(event, listener) {
+    return this.off(event, listener);
+  }
+  removeAllListeners(event) {
+    if (event === undefined) {
+      this.#listeners.clear();
+    } else {
+      this.#listeners.delete(event);
+    }
+    return this;
+  }
+  emit(event, ...arguments_) {
+    const entries = this.#listeners.get(event);
+    if (!entries || entries.length === 0) {
+      if (event === "error") {
+        const error = arguments_[0];
+        if (error instanceof Error)
+          throw error;
+        throw new Error(`Unhandled error. (${String(error)})`);
+      }
+      return false;
+    }
+    for (const entry of [...entries]) {
+      if (entry.once)
+        this.#remove(event, entry);
+      entry.listener.apply(this, arguments_);
+    }
+    return true;
+  }
+  listeners(event) {
+    return (this.#listeners.get(event) ?? []).map((entry) => entry.listener);
+  }
+  listenerCount(event) {
+    return this.#listeners.get(event)?.length ?? 0;
+  }
+  eventNames() {
+    return [...this.#listeners.keys()];
+  }
+  #remove(event, entry) {
+    const entries = this.#listeners.get(event);
+    const index = entries?.indexOf(entry) ?? -1;
+    if (index === -1)
+      return;
+    entries.splice(index, 1);
+    if (entries.length === 0)
+      this.#listeners.delete(event);
+  }
+  #add(event, listener, once, prepend) {
+    checkListener(listener);
+    let entries = this.#listeners.get(event);
+    if (!entries) {
+      entries = [];
+      this.#listeners.set(event, entries);
+    }
+    const entry = { listener, once };
+    if (prepend) {
+      entries.unshift(entry);
+    } else {
+      entries.push(entry);
+    }
+    return this;
+  }
+}
+function checkListener(listener) {
+  if (typeof listener !== "function") {
+    throw new TypeError(`The "listener" argument must be a function. Received ${typeof listener}`);
+  }
+}
+
 // src/StreamParser.js
-import { EventEmitter } from "events";
 var DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 
 class StreamParseError extends Error {
@@ -3094,7 +3190,7 @@ class StreamParseError extends Error {
   }
 }
 
-class StreamParser extends EventEmitter {
+class StreamParser extends Emitter {
   constructor(options = {}) {
     super();
     this.parser = options.parser ?? new Parser(options);

package/index.d.ts

@@ -251,7 +251,10 @@ export class StreamParseError extends Error {
   snippet: string;
 }
 
-/** Incrementally emits complete top-level Links Notation records. */
+/**
+ * Incrementally emits complete top-level Links Notation records. Its listener
+ * methods mirror Node.js EventEmitter without depending on Node built-ins.
+ */
 export class StreamParser {
   parser: Parser;
   comments: boolean;
@@ -282,6 +285,21 @@ export class StreamParser {
   once(event: 'end', listener: (links: Link[]) => void): this;
   once(event: 'error', listener: (error: Error) => void): this;
   off(event: string, listener: (...arguments_: any[]) => void): this;
+  addListener(event: string, listener: (...arguments_: any[]) => void): this;
+  removeListener(event: string, listener: (...arguments_: any[]) => void): this;
+  prependListener(
+    event: string,
+    listener: (...arguments_: any[]) => void
+  ): this;
+  prependOnceListener(
+    event: string,
+    listener: (...arguments_: any[]) => void
+  ): this;
+  removeAllListeners(event?: string): this;
+  emit(event: string, ...arguments_: any[]): boolean;
+  listeners(event: string): Array<(...arguments_: any[]) => void>;
+  listenerCount(event: string): number;
+  eventNames(): string[];
 
   /** Lazily parse a synchronous iterable of chunks. */
   static parse(

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "links-notation",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
   "types": "index.d.ts",
   "type": "module",
   "scripts": {
-    "build": "bun run build:grammar && bun build src/index.js --outdir=dist --target=node",
+    "build": "bun run build:grammar && bun build src/index.js --outdir=dist --target=browser",
     "build:grammar": "peggy --format es -o src/parser-generated.js src/grammar.pegjs",
     "test": "bun test",
     "test:watch": "bun test --watch",
@@ -33,7 +33,7 @@
   "homepage": "https://github.com/link-foundation/links-notation#readme",
   "devDependencies": {
     "bun-types": "^1.4.3",
-    "eslint": "^10.12.0",
+    "eslint": "^10.13.0",
     "peggy": "^5.1.0",
     "prettier": "^3.9.10",
     "typescript": "^7.0.2"

package/src/Emitter.js

@@ -0,0 +1,134 @@
+/**
+ * A dependency-free event emitter with the Node.js `EventEmitter` methods that
+ * StreamParser documents.
+ *
+ * Importing Node's built-in `events` module made every bundle of the package
+ * entry point, including parser-only browser bundles, fail to resolve `events`
+ * unless the consumer installed a polyfill (issue #351). This class runs
+ * unchanged in browsers, Node.js, Bun, and Deno. It keeps Node's semantics:
+ * listeners run synchronously in registration order, and emitting `error`
+ * without a listener throws the error. It also works with Node's
+ * `events.once()` and `events.on()` helpers.
+ */
+export class Emitter {
+  #listeners = new Map();
+
+  /** Add a listener for an event. */
+  on(event, listener) {
+    return this.#add(event, listener, false, false);
+  }
+
+  /** Alias of on(), as in Node.js. */
+  addListener(event, listener) {
+    return this.on(event, listener);
+  }
+
+  /** Add a listener that runs before the existing ones. */
+  prependListener(event, listener) {
+    return this.#add(event, listener, false, true);
+  }
+
+  /** Add a listener that is removed after its first call. */
+  once(event, listener) {
+    return this.#add(event, listener, true, false);
+  }
+
+  /** Add a one-time listener that runs before the existing ones. */
+  prependOnceListener(event, listener) {
+    return this.#add(event, listener, true, true);
+  }
+
+  /** Remove the most recently added registration of a listener. */
+  off(event, listener) {
+    checkListener(listener);
+    const entries = this.#listeners.get(event);
+    if (!entries) return this;
+    const entry = entries.findLast((entry) => entry.listener === listener);
+    if (entry) this.#remove(event, entry);
+    return this;
+  }
+
+  /** Alias of off(), as in Node.js. */
+  removeListener(event, listener) {
+    return this.off(event, listener);
+  }
+
+  /** Remove the listeners of one event, or of every event. */
+  removeAllListeners(event) {
+    if (event === undefined) {
+      this.#listeners.clear();
+    } else {
+      this.#listeners.delete(event);
+    }
+    return this;
+  }
+
+  /**
+   * Call the listeners of an event with the given arguments and return whether
+   * there were any. An `error` event without listeners throws its argument.
+   */
+  emit(event, ...arguments_) {
+    const entries = this.#listeners.get(event);
+    if (!entries || entries.length === 0) {
+      if (event === 'error') {
+        const error = arguments_[0];
+        if (error instanceof Error) throw error;
+        throw new Error(`Unhandled error. (${String(error)})`);
+      }
+      return false;
+    }
+    // Listeners added or removed while emitting take effect on the next emit.
+    for (const entry of [...entries]) {
+      if (entry.once) this.#remove(event, entry);
+      entry.listener.apply(this, arguments_);
+    }
+    return true;
+  }
+
+  /** Return a copy of the listeners of an event. */
+  listeners(event) {
+    return (this.#listeners.get(event) ?? []).map((entry) => entry.listener);
+  }
+
+  /** Return the number of listeners of an event. */
+  listenerCount(event) {
+    return this.#listeners.get(event)?.length ?? 0;
+  }
+
+  /** Return the names of events that have listeners. */
+  eventNames() {
+    return [...this.#listeners.keys()];
+  }
+
+  #remove(event, entry) {
+    const entries = this.#listeners.get(event);
+    const index = entries?.indexOf(entry) ?? -1;
+    if (index === -1) return;
+    entries.splice(index, 1);
+    if (entries.length === 0) this.#listeners.delete(event);
+  }
+
+  #add(event, listener, once, prepend) {
+    checkListener(listener);
+    let entries = this.#listeners.get(event);
+    if (!entries) {
+      entries = [];
+      this.#listeners.set(event, entries);
+    }
+    const entry = { listener, once };
+    if (prepend) {
+      entries.unshift(entry);
+    } else {
+      entries.push(entry);
+    }
+    return this;
+  }
+}
+
+function checkListener(listener) {
+  if (typeof listener !== 'function') {
+    throw new TypeError(
+      `The "listener" argument must be a function. Received ${typeof listener}`
+    );
+  }
+}

package/src/StreamParser.js

@@ -1,4 +1,4 @@
-import { EventEmitter } from 'events';
+import { Emitter } from './Emitter.js';
 import { Parser } from './Parser.js';
 import { DelimitedReferences } from './quotes.js';
 
@@ -39,7 +39,7 @@ export class StreamParseError extends Error {
  * uses the regular Parser as the source of truth, which keeps quoted strings,
  * nested contexts, comments, and future grammar changes in one place.
  */
-export class StreamParser extends EventEmitter {
+export class StreamParser extends Emitter {
   constructor(options = {}) {
     super();
     this.parser = options.parser ?? new Parser(options);

package/tests/BrowserBundle.test.js

@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test';
+import { on, once } from 'node:events';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, URL } from 'node:url';
+import { Emitter } from '../src/Emitter.js';
+import { Parser, StreamParser } from '../src/index.js';
+
+const source = fileURLToPath(new URL('../src/index.js', import.meta.url));
+const published = fileURLToPath(new URL('../dist/index.js', import.meta.url));
+
+// Bundlers such as esbuild (`--platform=browser`) cannot resolve Node built-ins
+// like `events`, so any bare import in the package graph breaks browser builds
+// unless consumers add a polyfill (issue #351). Bun's own browser target would
+// silently polyfill them, so this plugin fails on every bare import instead.
+const rejectBareImports = (imports) => ({
+  name: 'reject-bare-imports',
+  setup(build) {
+    build.onResolve({ filter: /^[^./]/ }, (args) => {
+      imports.push(`${args.path} (from ${args.importer})`);
+      return { path: args.path, external: true };
+    });
+  },
+});
+
+async function bundleForBrowser(entrypoint) {
+  const imports = [];
+  const result = await globalThis.Bun.build({
+    entrypoints: [entrypoint],
+    target: 'browser',
+    plugins: [rejectBareImports(imports)],
+  });
+  return { result, imports };
+}
+
+describe('browser bundling (issue #351)', () => {
+  test('the source entry point imports no Node built-ins or packages', async () => {
+    const { result, imports } = await bundleForBrowser(source);
+    expect(result.success).toBe(true);
+    expect(imports).toEqual([]);
+  });
+
+  test('the published dist entry point imports no Node built-ins or packages', async () => {
+    const { result, imports } = await bundleForBrowser(published);
+    expect(result.success).toBe(true);
+    expect(imports).toEqual([]);
+
+    const text = readFileSync(published, 'utf8');
+    expect(text).not.toMatch(/^\s*import\s[^;]*from\s*["'][^./]/m);
+    expect(text).not.toMatch(/\brequire\(\s*["']/);
+  });
+
+  test('the dist bundle parses and streams like the source', async () => {
+    const dist = await import(published);
+    const input = '(law: text)\nnext value';
+    expect(dist.formatLinks(new dist.Parser().parse(input))).toBe(
+      dist.formatLinks(new Parser().parse(input))
+    );
+
+    const stream = new dist.StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link.toString()));
+    stream.end(input);
+    expect(seen).toEqual(['(law: text)', '(next value)']);
+  });
+});
+
+describe('Emitter', () => {
+  test('calls listeners in order with the emitter as this', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    emitter.on('event', function (value) {
+      calls.push(['first', value, this === emitter]);
+    });
+    emitter.addListener('event', (value) => calls.push(['second', value]));
+    emitter.prependListener('event', (value) => calls.push(['zeroth', value]));
+
+    expect(emitter.emit('event', 1)).toBe(true);
+    expect(calls).toEqual([
+      ['zeroth', 1],
+      ['first', 1, true],
+      ['second', 1],
+    ]);
+    expect(emitter.emit('missing')).toBe(false);
+  });
+
+  test('once listeners run a single time', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    emitter.once('event', (value) => calls.push(`once ${value}`));
+    emitter.prependOnceListener('event', (value) => calls.push(`pre ${value}`));
+    emitter.emit('event', 1);
+    emitter.emit('event', 2);
+    expect(calls).toEqual(['pre 1', 'once 1']);
+    expect(emitter.listenerCount('event')).toBe(0);
+  });
+
+  test('off removes the latest registration, including once listeners', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    const listener = (value) => calls.push(value);
+    emitter.on('event', listener);
+    emitter.on('event', listener);
+    emitter.off('event', listener);
+    emitter.emit('event', 'a');
+    emitter.removeListener('event', listener);
+    emitter.emit('event', 'b');
+    emitter.once('event', listener);
+    emitter.off('event', listener);
+    emitter.emit('event', 'c');
+    expect(calls).toEqual(['a']);
+    expect(emitter.eventNames()).toEqual([]);
+  });
+
+  test('listener changes during emit take effect on the next emit', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    const second = () => calls.push('second');
+    emitter.on('event', () => {
+      calls.push('first');
+      emitter.off('event', second);
+      emitter.on('event', () => calls.push('added'));
+    });
+    emitter.on('event', second);
+    emitter.emit('event');
+    expect(calls).toEqual(['first', 'second']);
+  });
+
+  test('inspects and removes listeners', () => {
+    const emitter = new Emitter();
+    const listener = () => {};
+    emitter.on('a', listener).on('b', listener).on('b', listener);
+    expect(emitter.listeners('b')).toEqual([listener, listener]);
+    expect(emitter.listenerCount('b')).toBe(2);
+    expect(emitter.eventNames()).toEqual(['a', 'b']);
+    emitter.removeAllListeners('b');
+    expect(emitter.eventNames()).toEqual(['a']);
+    emitter.removeAllListeners();
+    expect(emitter.listenerCount('a')).toBe(0);
+  });
+
+  test('an unhandled error event throws like Node.js', () => {
+    const emitter = new Emitter();
+    const error = new Error('boom');
+    expect(() => emitter.emit('error', error)).toThrow(error);
+    expect(() => emitter.emit('error', 'text')).toThrow(
+      'Unhandled error. (text)'
+    );
+    emitter.on('error', () => {});
+    expect(emitter.emit('error', error)).toBe(true);
+  });
+
+  test('rejects listeners that are not functions', () => {
+    expect(() => new Emitter().on('event', 'nope')).toThrow(TypeError);
+  });
+
+  test('works with the Node.js events.once helper', async () => {
+    const stream = new StreamParser();
+    const ended = once(stream, 'end');
+    stream.end('a b');
+    const [links] = await ended;
+    expect(links.map(String)).toEqual(['(a b)']);
+  });
+
+  test('works with the Node.js events.on async iterator', async () => {
+    const stream = new StreamParser();
+    const controller = new globalThis.AbortController();
+    const links = on(stream, 'link', { signal: controller.signal });
+    globalThis.setTimeout(() => stream.end('a b\nc d'), 0);
+    const seen = [];
+    try {
+      for await (const [link] of links) {
+        seen.push(String(link));
+        if (seen.length === 2) controller.abort();
+      }
+    } catch (error) {
+      if (error.name !== 'AbortError') throw error;
+    }
+    expect(seen).toEqual(['(a b)', '(c d)']);
+    expect(stream.listenerCount('link')).toBe(0);
+    expect(stream.listenerCount('error')).toBe(0);
+  });
+
+  test('StreamParser still throws the stream error without a listener', () => {
+    const stream = new StreamParser();
+    expect(() => stream.write(1)).toThrow(TypeError);
+  });
+});