rdfjs-query-interfaces.ts

interface Queryable<SourceType> {
  query(query: string, context?: QueryStringContext<SourceType>): Promise<QueryResult>
}
    
interface QueryableAlgebra<SourceType> {
  query(query: Algebra, context?: QueryAlgebraContext<SourceType>): Promise<QueryResult>
}

// TODO: what about update queries?

type QueryResult = QueryResultBindings | QueryResultQuads | QueryResultBoolean; // TODO: should we open this up for other types?

interface QueryResultBindings {
  type: 'bindings';
  metadata: () => Metadata;
  bindings: Stream<Bindings>; // This should be a lazy stream
  variables: RDF.Variable[];
}
    
interface QueryResultQuads {
  type: 'quads';
  metadata: () => Metadata;
  quads: Stream<RDF.Quad>; // This should be a lazy stream
}

interface QueryResultBoolean {
  type: 'boolean';
  metadata: () => Metadata; // TODO: do we need this here?
  booleanResult: Promise<boolean>; // TODO: make this lazy behind a lambda?
}
    
interface Metadata {
  cardinality?: number; // Cardinality estimate
  [key: string]: any; // For any other custom metadata entries.
}
    
interface Bindings {
  type: 'bindings';
  get(variable: RDF.Variable): RDF.Term;
  keys(): RDF.Variable[];
  entries(): [RDF.Variable, RDF.Term][];
  size: number;
}
    
interface BindingsFactory {
  createBindings(entries: [RDF.Variable, RDF.Term][]): Bindings;
  mergeBindings(bindings: Bindings[]): Bindings;
}

// SourceType can be anything the query engine defines
// TODO: we may consider defining some standards, like 'string', RDF.Source, ...
interface QueryContext<SourceType> {
  sources?: SourceType[];
  queryTimestamp?: Date; // Required for certain SPARQL operations such as NOW().
  [key: string]: any; // For any other custom metadata entries.
}
    
interface QueryStringContext<SourceType> extends QueryContext<SourceType> {
  queryFormat?: QueryFormat; // defaults to { language: 'SPARQL', version: '1.1', extensions: [] }
  baseIRI?: string; // Required for parsing SPARQL queries
};

interface QueryAlgebraContext<SourceType> extends QueryContext<SourceType> {};
    
interface QueryFormat {
  language: string; // Like 'SPARQL'
  version: string; // Like '1.1'
  extensions: string[]; // TODO: leave the syntax of these extensions open for now?
}
  
type Algebra = {}; // TODO: define this (possible starting point: https://github.com/joachimvh/SPARQLAlgebra.js)