fix: make import() return an awaitable promise for the store

[jeswr]

Makes Store#import() awaitable: the returned stream is wrapped in a proxy that forwards then/catch/finally to a completion promise resolving to the store itself, satisfying the RDF/JS Dataset.import(stream): Promise<Dataset> signature while keeping the existing Sink.import(stream): EventEmitter behaviour intact for callers that never await.

Supersedes #503, reworked per the review notes there:

• Breaking, so next major: a thenable return value changes any async function that returns the result of import() — it now awaits stream completion and resolves to the store instead of the stream. Labelled semver.major accordingly.
• No eager promise, no unhandled rejections: the completion promise and its end/error listeners are only created upon first access of then/catch/finally. Non-awaiting Sink-style callers observe zero change: no listeners are added and an unlistened error event still throws loudly (an eagerly attached error listener — even guarded with a no-op catch — was verified to silently swallow such errors instead), and no rejection ever exists to go unhandled.
• No EventEmitter/Store proxy as the resolution value: the promise resolves to plain this, which is all Promise<Store> requires; the returned wrapper otherwise behaves as the stream.
• Errored streams reject: the already-completed check consults stream.errored before the ended/destroyed/non-readable checks, so a stream that has already errored (e.g. via destroy(error)) rejects instead of resolving as if it had ended.

Refs #298 #435 #503

cc @jeswr

[Copilot]

Pull request overview

This PR updates Store#import() to be RDF/JS Dataset.import(stream): Promise<Dataset>-compatible by making the returned value awaitable (thenable), while still allowing existing Sink-style usage that treats the return value as a stream/EventEmitter.

Changes:

• Wrap the returned import stream in a Proxy that exposes then/catch/finally to await completion and resolve to the store instance.
• Lazily create the completion promise only when then/catch/finally is accessed to avoid eager listeners and unhandled rejections for non-awaiting callers.
• Add tests covering awaiting behavior, repeated promise access, already-ended/destroyed inputs, and error/unhandled-rejection scenarios.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/N3Store.js	Makes import() return a thenable stream wrapper that can be awaited to get the store on completion.
test/N3Store-test.js	Adds a dedicated test suite validating promise-like behavior and preserving EventEmitter usage expectations.

Suppressed comments (1)

src/N3Store.js:516

• The Proxy wrapper does not preserve method this binding. For example, imported.on('end', ...) will call the stream's on with this === proxy, so listener state is stored on the proxy rather than the underlying stream; events emitted by stream (the target) won't reach listeners registered on the proxy. To truly “behave as the stream”, the get trap should return functions bound to target (or otherwise ensure calls execute with this === target), ideally with caching so repeated gets return the same bound function.

        }
        return target[property];
      },
    });
  }

  // ### `removeQuad` removes a quad from the store if it exists
  removeQuad(subject, predicate, object, graph) {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.