jsonld-streaming-parser
Version:
A fast and lightweight streaming JSON-LD parser
228 lines (227 loc) • 8.71 kB
TypeScript
import * as RDF from "@rdfjs/types";
import { IDocumentLoader, JsonLdContext } from "jsonld-context-parser";
import { Transform } from "readable-stream";
import { IEntryHandler } from "./entryhandler/IEntryHandler";
import EventEmitter = NodeJS.EventEmitter;
/**
* A stream transformer that parses JSON-LD (text) streams to an {@link RDF.Stream}.
*/
export declare class JsonLdParser extends Transform implements RDF.Sink<EventEmitter, RDF.Stream> {
static readonly DEFAULT_PROCESSING_MODE: string;
static readonly ENTRY_HANDLERS: IEntryHandler<any>[];
private readonly options;
private readonly parsingContext;
private readonly util;
private readonly jsonParser;
private readonly contextJobs;
private readonly typeJobs;
private readonly contextAwaitingJobs;
private lastDepth;
private lastKeys;
private lastOnValueJob;
constructor(options?: IJsonLdParserOptions);
/**
* Construct a JsonLdParser from the given HTTP response.
*
* This will throw an error if no valid JSON response is received
* (application/ld+json, application/json, or something+json).
*
* For raw JSON responses, exactly one link header pointing to a JSON-LD context is required.
*
* This method is not responsible for handling redirects.
*
* @param baseIRI The URI of the received response.
* @param mediaType The received content type.
* @param headers Optional HTTP headers.
* @param options Optional parser options.
*/
static fromHttpResponse(baseIRI: string, mediaType: string, headers?: Headers, options?: IJsonLdParserOptions): JsonLdParser;
/**
* Parses the given text stream into a quad stream.
* @param {NodeJS.EventEmitter} stream A text stream.
* @return {RDF.Stream} A quad stream.
*/
import(stream: EventEmitter): RDF.Stream;
_transform(chunk: any, encoding: string, callback: (error?: Error | null, data?: any) => void): void;
/**
* Start a new job for parsing the given value.
*
* This will let the first valid {@link IEntryHandler} handle the entry.
*
* @param {any[]} keys The stack of keys.
* @param value The value to parse.
* @param {number} depth The depth to parse at.
* @param {boolean} lastDepthCheck If the lastDepth check should be done for buffer draining.
* @return {Promise<void>} A promise resolving when the job is done.
*/
newOnValueJob(keys: any[], value: any, depth: number, lastDepthCheck: boolean): Promise<void>;
/**
* Flush the processing stacks at the given depth.
* @param {number} depth A depth.
*/
flushStacks(depth: number): void;
/**
* Flush buffers for the given depth.
*
* This should be called after the last entry at a given depth was processed.
*
* @param {number} depth A depth.
* @param {any[]} keys A stack of keys.
* @return {Promise<void>} A promise resolving if flushing is done.
*/
flushBuffer(depth: number, keys: any[]): Promise<void>;
/**
* Check if at least one {@link IEntryHandler} validates the entry to true.
* @param {any[]} keys A stack of keys.
* @param {number} depth A depth.
* @param {boolean} inProperty If the current depth is part of a valid property node.
* @return {Promise<{ valid: boolean, property: boolean }>} A promise resolving to true or false.
*/
protected validateKey(keys: any[], depth: number, inProperty: boolean): Promise<{
valid: boolean;
property: boolean;
}>;
/**
* Attach all required listeners to the JSON parser.
*
* This should only be called once.
*/
protected attachJsonParserListeners(): void;
/**
* Check if the parser is currently parsing an element that is part of an @context entry.
* @param {number} depth A depth.
* @return {boolean} A boolean.
*/
protected isParsingContextInner(depth: number): boolean;
/**
* Execute all buffered jobs.
* @return {Promise<void>} A promise resolving if all jobs are finished.
*/
protected executeBufferedJobs(): Promise<void>;
}
/**
* Constructor arguments for {@link JsonLdParser}
*/
export interface IJsonLdParserOptions {
/**
* A data factory.
*/
dataFactory?: RDF.DataFactory<RDF.BaseQuad>;
/**
* The root context.
*/
context?: JsonLdContext;
/**
* The base IRI.
*/
baseIRI?: string;
/**
* If this parser can assume that parsed documents follow the streaming JSON-LD profile.
* If true, and a non-streaming document is detected, an error may be thrown.
* If false, non-streaming documents will be handled by preemptively buffering entries,
* which will lose many of the streaming benefits of this parser.
*
* Concretely, if true, @context definitions must come as first object entries,
* followed by @type (if they define a type-scoped context).
*
* Defaults to false for spec-compliance.
*/
streamingProfile?: boolean;
/**
* Loader for remote contexts.
*/
documentLoader?: IDocumentLoader;
/**
* If the lack of JSON-LD context link headers on raw JSON documents should NOT result in an error.
* If true, raw JSON documents can be considered first-class JSON-LD documents.
*/
ignoreMissingContextLinkHeader?: boolean;
/**
* If blank node predicates should be allowed,
* they will be ignored otherwise.
* Defaults to false.
*/
produceGeneralizedRdf?: boolean;
/**
* The maximum JSON-LD version that should be processable by this parser.
* Defaults to JsonLdParser.DEFAULT_PROCESSING_MODE.
*/
processingMode?: string;
/**
* By default, JSON-LD requires that
* all properties (or @id's) that are not URIs,
* are unknown keywords,
* and do not occur in the context
* should be silently dropped.
* When setting this value to true,
* an error will be thrown when such properties occur.
*
* This also applies to invalid values such as language tags.
*
* Defaults to false.
*/
strictValues?: boolean;
/**
* If RDF lists can appear in the subject position.
* Defaults to false.
*/
allowSubjectList?: boolean;
/**
* If @index inside array nodes should be validated.
* I.e., nodes inside the same array with the same @id,
* should have equal @index values.
* This is not applicable to this parser as we don't do explicit flattening,
* but it is required to be spec-compliant.
* Defaults to false.
*
* Spec-compliance: to be fully spec-compliant,
* this must be explicitly set to true.
*/
validateValueIndexes?: boolean;
/**
* The graph to use as default graph when no explicit @graph is set.
* Defaults to dataFactory.defaultGraph().
*/
defaultGraph?: RDF.NamedNode | RDF.BlankNode | RDF.DefaultGraph;
/**
* The mode by which the values with a certain base direction should be transformed into RDF.
* * 'i18n-datatype': objects have a https://www.w3.org/ns/i18n# datatype.
* * 'compound-literal': reified values using rdf:value, rdf:direction and rdf:language.
*/
rdfDirection?: 'i18n-datatype' | 'compound-literal';
/**
* If language tags should be normalized to lowercase.
* This is always true for JSON-LD 1.0,
* but false by default for all following versions.
*/
normalizeLanguageTags?: boolean;
/**
* When the streaming profile flag is enabled,
* `@type` entries MUST come before other properties since they may defined a type-scoped context.
* However, when this flag is enabled, `@type` entries that do NOT
* define a type-scoped context may appear anywhere just like a regular property.
*/
streamingProfileAllowOutOfOrderPlainType?: boolean;
/**
* If JSON-LD context validation should be skipped.
*
* This is useful when parsing large contexts that are known to be valid.
*/
skipContextValidation?: boolean;
/**
* If embedded nodes and annotated objects should be parsed according to the JSON-LD star specification.
* Defaults to true
*/
rdfstar?: boolean;
/**
* If embedded nodes may use reverse properties
* Defaults to false.
*/
rdfstarReverseInEmbedded?: boolean;
/**
* If the APIs you interact with publish valid JSON-LD on media types that are not application/ld+json,
* provide those content-types in this array.
* Default to ['application/activity+json']
*/
wellKnownMediaTypes?: string[];
}