rdfjs-jelly 0.2.0 → 0.2.1

package/README.md

@@ -13,7 +13,7 @@ Jelly-RDF and Jelly-SPARQL binary parsers and writers using RDF/JS terms, for No
 ## Support
 
 - Reads Jelly-RDF 1.0, 1.1, and 1.2 (protocol tags 1, 2, and 3).
-- Writes Jelly-RDF 1.1 by default; opt into 1.2 with `version: 3`.
+- Writes packed Jelly-RDF 1.2 by default; use `version: 2` for Jelly 1.1.
 - Supports physical triple, quad, and graph streams; delimited and non-delimited encoding; lookup/repeated-term compression; namespaces; and message metadata.
 - Reads and writes Jelly-SPARQL 1.0 SELECT and ASK result sets, including punctuated streams.
 - Uses RDF/JS terms and accepts a custom RDF/JS data factory.
@@ -98,7 +98,9 @@ writer.end((error, bytes) => {
 });
 ```
 
-`Writer` emits a delimited Jelly 1.1 stream (protocol tag 2) by default. Set
+`Writer`, Node `StreamWriter`, and browser `StreamWriter` emit delimited Jelly 1.2
+streams (protocol tag 3) with message packing enabled by default. Use `version: 2`
+for Jelly 1.1 compatibility. Set
 `delimited: false` for one bare protobuf frame. All output must fit in that frame;
 a Jelly 1.2 frame can contain several logical messages when packing is enabled.
 
@@ -108,7 +110,7 @@ a Jelly 1.2 frame can contain several logical messages when packing is enabled.
 introduces a column layout (protocol tag **3**), packed lookup entries, repeat
 runs, RDF 1.2 terms, explicit RDF Message boundaries, and concatenable streams.
 The parser selects the layout from the stream options. Existing 1.0/1.1 streams
-remain readable, and the default writer stays on 1.1 for older consumers.
+remain readable; pass `version: 2` to write Jelly 1.1 for older consumers.
 
 ```ts
 import { DataFactory, Parser, Writer, RdfStreamType, RdfVersion } from 'rdfjs-jelly';
@@ -157,7 +159,7 @@ callback it throws. Flushing requires delimited output. Packing has no timer:
 use explicit flushes or `packMessages: false` for latency-sensitive delivery.
 
 The 1.2 layout supports `TRIPLES` and `QUADS`. Use `QUADS` for named graphs;
-`GRAPHS`, `addGraph()`, and `logicalType` belong to the older layout. Use
+`GRAPHS`, `addGraph()`, and `logicalType` require `version: 2`. Use
 `streamType` (`FLAT` or `MESSAGES`) instead. `rdfVersion` defaults to RDF 1.2;
 writers reject terms that the declared version cannot represent. Custom factories
 must preserve direction and `rdf:dirLangString` for directional literals.
@@ -232,6 +234,57 @@ With `messages: true`, output items are wrapped entries and a `messageCounter`
 event accompanies each quad. Quad-only output cannot represent empty messages;
 retain the `message` events if forwarding a message stream.
 
+## Quad-pattern filtering
+
+Since 0.2.1, `Parser`, Node `StreamParser`, and browser `StreamParser` accept
+`quadPatterns`:
+
+```ts
+import { DataFactory, Parser } from 'rdfjs-jelly';
+
+const parser = new Parser({
+  quadPatterns: [
+    { predicate: DataFactory.namedNode('http://example.org/name') },
+    { predicate: DataFactory.namedNode('http://example.org/knows') },
+  ],
+});
+const selectedQuads = parser.parse(bytes);
+```
+
+Patterns are combined with OR; positions within a pattern are combined with AND.
+An omitted or `null` position is a wildcard. Omit `quadPatterns` to select all
+quads; `[]` selects none, and `[{}]` selects all. Matching preserves input order
+and duplicates, without duplicating quads that match several patterns.
+`QuadPattern` is exported as a TypeScript type.
+
+Jelly 1.2 matches column values before constructing RDF/JS terms or quads. When
+every pattern pins the same position (subject, object, predicate or graph) to an
+IRI, that column alone chooses the rows: each distinct IRI is judged once, and the
+other columns, including literal text, are built only for the selected rows. Only
+selected values reach your data factory. Patterns that also constrain other
+positions are checked on those few candidates. Patterns that share no IRI-pinned
+position (for example a literal-only object, or an OR of patterns on different
+positions) use a slower path that, in our measurements, is not faster than
+parsing everything and filtering afterwards.
+Lookup updates and validation still run for rejected statements, so malformed
+input is still rejected. Errors that depend on your data factory, such as a
+directional literal it cannot build, surface only for selected statements. The
+filter does not skip bytes, files or decompression.
+Jelly 1.0/1.1 also support filtering, after term decoding and before quad creation.
+Namespaces remain available regardless of the filter. See
+[PERFORMANCE.md](PERFORMANCE.md#pushing-down-a-filter-to-the-parser) for measurements.
+
+Filtering keeps empty messages, message counters and metadata. A message with no
+matching quads becomes empty; use `parseMessages()` or stream `message` events to
+retain its boundary. Plain quad output contains only selected statements.
+
+Terms match by kind and value. Literal equality includes datatype, language
+(case-insensitive) and direction; plain strings equal explicit `xsd:string`
+literals. Triple terms match recursively. Graph patterns distinguish named,
+blank-node and default graphs. Blank-node patterns use the labels in parser
+output, including the opaque message scope in Jelly 1.2; raw labels from the
+input are not identifiers across independent messages.
+
 ## SPARQL result sets
 
 [Jelly-SPARQL 1.0.0](https://jelly-rdf.github.io/1.2.x/specification/sparql/)

package/dist/browser/index.d.mts

@@ -71,7 +71,18 @@ interface StreamOptions {
     streamType?: RdfStreamType;
     rdfVersion?: RdfVersion;
 }
+/** Positions within a pattern are ANDed; patterns are ORed. Omitted or null
+ * positions are wildcards. Blank-node labels refer to parser output labels. */
+interface QuadPattern {
+    subject?: RDF.Term | null;
+    predicate?: RDF.Term | null;
+    object?: RDF.Term | null;
+    graph?: RDF.Term | null;
+}
 interface ParserOptions {
+    /** Select quads before RDF/JS materialization in Jelly 1.2. An empty array
+     * selects no quads. Message boundaries, counters and metadata are retained. */
+    quadPatterns?: readonly QuadPattern[];
     factory?: RDF.DataFactory;
     delimited?: boolean | 'auto';
     strict?: boolean;
@@ -105,7 +116,7 @@ interface WriterOptions {
     streamName?: string;
     namespaces?: Record<string, string | RDF.NamedNode>;
     lookup?: Partial<LookupPreset>;
-    /** Protocol tag: 2 = Jelly 1.1 (default), 3 = Jelly 1.2. */
+    /** Protocol tag: 2 = Jelly 1.1, 3 = Jelly 1.2 (default). */
     version?: 2 | 3;
     streamType?: RdfStreamType;
     rdfVersion?: RdfVersion;
@@ -2976,6 +2987,7 @@ interface DecoderEvents {
     options?: OptionsListener;
 }
 declare class Decoder {
+    private readonly patterns;
     private columns?;
     private columnReader?;
     private readonly parserOptions;
@@ -3009,6 +3021,7 @@ declare class Decoder {
     decodeProtoPayloadTo(rawReader: unknown, length: number, output: RDF.Quad[]): void;
     private consumeProtoRow;
     private emitQuad;
+    private makeQuad;
     private decodeWireLookupEntry;
     private decodeWireTriple;
     /**
@@ -3197,10 +3210,18 @@ declare class LookupDecoder {
      * declare a large table without the parser paying for entries it never fills.
      */
     private readonly data;
+    /** Version of each slot, changed by every assignment; zero while unassigned. */
+    private readonly stamps;
     private lastAssignedIndex;
     private lastReusedIndex;
+    /** Called with the index of an assigned entry just before it is overwritten, the only way a value derived from an entry can go stale. */
+    onReplace?: (index: number) => void;
+    /** Entries `1..contiguous` are all assigned, so a reference up to it needs no further check. */
+    contiguous: number;
     constructor(size: number, limit?: number);
     assign(index: number, value: string): void;
+    /** Version of the entry at `index`, or 0 when it is outside the table or unassigned. */
+    stamp(index: number): number;
     /** Extend the backing array by doubling, staying packed and capped at the table size. */
     private reserve;
     private at;
@@ -3515,4 +3536,4 @@ declare class StreamWriter {
     import(stream: ReadableStream<RDF.Quad | MessageQuad>): ReadableStream<Uint8Array>;
 }
 
-export { type BinaryInput, type BinaryOutput, BlankNode, type BrowserStreamChunk, ColumnEncoder, DEFAULT_LOOKUP_PRESET, DataFactory, Decoder, DefaultGraph, Encoder, JellyConformanceError, JellyError, JellySparqlResultError, JellyUnsupportedFeatureError, Literal, LogicalStreamType, LookupDecoder, LookupEncoder, type LookupPreset, MAX_LOOKUP_SIZE, MIN_NAME_LOOKUP_SIZE, Message, MessageDecoder, MessageEncoder, type MessageMetadata, type MessageQuad, type MessageQuadArray, NamedNode, type ParseCallback, Parser, type ParserOptions, type ParserOutput, type ParserOutputItem, PhysicalStreamType, Quad, RDF_DIR_LANG_STRING, RDF_LANG_STRING, RdfStreamType, RdfVersion, SMALL_LOOKUP_PRESET, SparqlAskResult, type SparqlBinding, type SparqlEvent, SparqlParser, type SparqlParserOptions, type SparqlResult, type SparqlResultInfo, type SparqlResultMetadata, type SparqlSelectResult, SparqlStreamParser, SparqlStreamType, SparqlStreamWriter, type SparqlTerm, type SparqlWritableResult, SparqlWriter, type SparqlWriterOptions, type StreamOptions, StreamParser, StreamWriter, Variable, Writer, type WriterEndCallback, type WriterOptions, XSD_STRING, delimitedJellyHint, isMessageQuad, normalizeLookupPreset, toMessages };
+export { type BinaryInput, type BinaryOutput, BlankNode, type BrowserStreamChunk, ColumnEncoder, DEFAULT_LOOKUP_PRESET, DataFactory, Decoder, DefaultGraph, Encoder, JellyConformanceError, JellyError, JellySparqlResultError, JellyUnsupportedFeatureError, Literal, LogicalStreamType, LookupDecoder, LookupEncoder, type LookupPreset, MAX_LOOKUP_SIZE, MIN_NAME_LOOKUP_SIZE, Message, MessageDecoder, MessageEncoder, type MessageMetadata, type MessageQuad, type MessageQuadArray, NamedNode, type ParseCallback, Parser, type ParserOptions, type ParserOutput, type ParserOutputItem, PhysicalStreamType, Quad, type QuadPattern, RDF_DIR_LANG_STRING, RDF_LANG_STRING, RdfStreamType, RdfVersion, SMALL_LOOKUP_PRESET, SparqlAskResult, type SparqlBinding, type SparqlEvent, SparqlParser, type SparqlParserOptions, type SparqlResult, type SparqlResultInfo, type SparqlResultMetadata, type SparqlSelectResult, SparqlStreamParser, SparqlStreamType, SparqlStreamWriter, type SparqlTerm, type SparqlWritableResult, SparqlWriter, type SparqlWriterOptions, type StreamOptions, StreamParser, StreamWriter, Variable, Writer, type WriterEndCallback, type WriterOptions, XSD_STRING, delimitedJellyHint, isMessageQuad, normalizeLookupPreset, toMessages };

package/dist/browser/index.d.ts

@@ -71,7 +71,18 @@ interface StreamOptions {
     streamType?: RdfStreamType;
     rdfVersion?: RdfVersion;
 }
+/** Positions within a pattern are ANDed; patterns are ORed. Omitted or null
+ * positions are wildcards. Blank-node labels refer to parser output labels. */
+interface QuadPattern {
+    subject?: RDF.Term | null;
+    predicate?: RDF.Term | null;
+    object?: RDF.Term | null;
+    graph?: RDF.Term | null;
+}
 interface ParserOptions {
+    /** Select quads before RDF/JS materialization in Jelly 1.2. An empty array
+     * selects no quads. Message boundaries, counters and metadata are retained. */
+    quadPatterns?: readonly QuadPattern[];
     factory?: RDF.DataFactory;
     delimited?: boolean | 'auto';
     strict?: boolean;
@@ -105,7 +116,7 @@ interface WriterOptions {
     streamName?: string;
     namespaces?: Record<string, string | RDF.NamedNode>;
     lookup?: Partial<LookupPreset>;
-    /** Protocol tag: 2 = Jelly 1.1 (default), 3 = Jelly 1.2. */
+    /** Protocol tag: 2 = Jelly 1.1, 3 = Jelly 1.2 (default). */
     version?: 2 | 3;
     streamType?: RdfStreamType;
     rdfVersion?: RdfVersion;
@@ -2976,6 +2987,7 @@ interface DecoderEvents {
     options?: OptionsListener;
 }
 declare class Decoder {
+    private readonly patterns;
     private columns?;
     private columnReader?;
     private readonly parserOptions;
@@ -3009,6 +3021,7 @@ declare class Decoder {
     decodeProtoPayloadTo(rawReader: unknown, length: number, output: RDF.Quad[]): void;
     private consumeProtoRow;
     private emitQuad;
+    private makeQuad;
     private decodeWireLookupEntry;
     private decodeWireTriple;
     /**
@@ -3197,10 +3210,18 @@ declare class LookupDecoder {
      * declare a large table without the parser paying for entries it never fills.
      */
     private readonly data;
+    /** Version of each slot, changed by every assignment; zero while unassigned. */
+    private readonly stamps;
     private lastAssignedIndex;
     private lastReusedIndex;
+    /** Called with the index of an assigned entry just before it is overwritten, the only way a value derived from an entry can go stale. */
+    onReplace?: (index: number) => void;
+    /** Entries `1..contiguous` are all assigned, so a reference up to it needs no further check. */
+    contiguous: number;
     constructor(size: number, limit?: number);
     assign(index: number, value: string): void;
+    /** Version of the entry at `index`, or 0 when it is outside the table or unassigned. */
+    stamp(index: number): number;
     /** Extend the backing array by doubling, staying packed and capped at the table size. */
     private reserve;
     private at;
@@ -3515,4 +3536,4 @@ declare class StreamWriter {
     import(stream: ReadableStream<RDF.Quad | MessageQuad>): ReadableStream<Uint8Array>;
 }
 
-export { type BinaryInput, type BinaryOutput, BlankNode, type BrowserStreamChunk, ColumnEncoder, DEFAULT_LOOKUP_PRESET, DataFactory, Decoder, DefaultGraph, Encoder, JellyConformanceError, JellyError, JellySparqlResultError, JellyUnsupportedFeatureError, Literal, LogicalStreamType, LookupDecoder, LookupEncoder, type LookupPreset, MAX_LOOKUP_SIZE, MIN_NAME_LOOKUP_SIZE, Message, MessageDecoder, MessageEncoder, type MessageMetadata, type MessageQuad, type MessageQuadArray, NamedNode, type ParseCallback, Parser, type ParserOptions, type ParserOutput, type ParserOutputItem, PhysicalStreamType, Quad, RDF_DIR_LANG_STRING, RDF_LANG_STRING, RdfStreamType, RdfVersion, SMALL_LOOKUP_PRESET, SparqlAskResult, type SparqlBinding, type SparqlEvent, SparqlParser, type SparqlParserOptions, type SparqlResult, type SparqlResultInfo, type SparqlResultMetadata, type SparqlSelectResult, SparqlStreamParser, SparqlStreamType, SparqlStreamWriter, type SparqlTerm, type SparqlWritableResult, SparqlWriter, type SparqlWriterOptions, type StreamOptions, StreamParser, StreamWriter, Variable, Writer, type WriterEndCallback, type WriterOptions, XSD_STRING, delimitedJellyHint, isMessageQuad, normalizeLookupPreset, toMessages };
+export { type BinaryInput, type BinaryOutput, BlankNode, type BrowserStreamChunk, ColumnEncoder, DEFAULT_LOOKUP_PRESET, DataFactory, Decoder, DefaultGraph, Encoder, JellyConformanceError, JellyError, JellySparqlResultError, JellyUnsupportedFeatureError, Literal, LogicalStreamType, LookupDecoder, LookupEncoder, type LookupPreset, MAX_LOOKUP_SIZE, MIN_NAME_LOOKUP_SIZE, Message, MessageDecoder, MessageEncoder, type MessageMetadata, type MessageQuad, type MessageQuadArray, NamedNode, type ParseCallback, Parser, type ParserOptions, type ParserOutput, type ParserOutputItem, PhysicalStreamType, Quad, type QuadPattern, RDF_DIR_LANG_STRING, RDF_LANG_STRING, RdfStreamType, RdfVersion, SMALL_LOOKUP_PRESET, SparqlAskResult, type SparqlBinding, type SparqlEvent, SparqlParser, type SparqlParserOptions, type SparqlResult, type SparqlResultInfo, type SparqlResultMetadata, type SparqlSelectResult, SparqlStreamParser, SparqlStreamType, SparqlStreamWriter, type SparqlTerm, type SparqlWritableResult, SparqlWriter, type SparqlWriterOptions, type StreamOptions, StreamParser, StreamWriter, Variable, Writer, type WriterEndCallback, type WriterOptions, XSD_STRING, delimitedJellyHint, isMessageQuad, normalizeLookupPreset, toMessages };