diff --git a/query/queryable.d.ts b/query/queryable.d.ts index b51a40f..7a98c86 100644 --- a/query/queryable.d.ts +++ b/query/queryable.d.ts @@ -5,13 +5,9 @@ import * as RDF from '../data-model'; import { Bindings, Query, ResultStream } from './common'; /** - * Context objects provide a way to pass additional bits information to the query engine when executing a query. + * Context properties provide a way to pass additional bits information to the query engine when executing a query. */ -export interface QueryContext { - /** - * An array of data sources the query engine must use. - */ - sources?: [SourceType, ...SourceType[]]; +export interface QueryContext { /** * The date that should be used by SPARQL operations such as NOW(). */ @@ -23,9 +19,9 @@ export interface QueryContext { } /** - * Context object in the case the passed query is a string. + * Context properties in the case the passed query is a string. */ -export interface QueryStringContext extends QueryContext { +export interface QueryStringContext extends QueryContext { /** * The format in which the query string is defined. * Defaults to { language: 'sparql', version: '1.1' } @@ -38,9 +34,19 @@ export interface QueryStringContext extends QueryContext } /** - * Context object in the case the passed query is an algebra object. + * Context properties in the case the passed query is an algebra object. */ -export type QueryAlgebraContext = QueryContext; +export type QueryAlgebraContext = QueryContext; + +/** + * Context properties for engines that can query upon dynamic sets of sources. + */ +export interface QuerySourceContext { + /** + * An array of data sources the query engine must use. + */ + sources: [SourceType, ...SourceType[]]; +} /** * Represents a specific query format @@ -61,33 +67,18 @@ export interface QueryFormat { extensions?: string[]; } -/** - * Placeholder to represent SPARQL Algebra trees. - * Algebra typings are TBD. Reference implementations include: - * - https://www.npmjs.com/package/sparqlalgebrajs - */ -export type Algebra = any; - /** * Generic query engine interfaces. - * It allow engines to return any type of result object for any type of query. - * @param QueryFormatTypesAvailable The format of the query, either string or algebra object. - * @param SourceType The allowed sources over which queries can be executed. + * It allow engines to return any type of result object for string queries. * @param SupportedMetadataType The allowed metadata types. - * @param QueryType The allowed query types. * @param QueryStringContextType Type of the string-based query context. - * @param QueryAlgebraContextType Type of the algebra-based query context. */ -export interface Queryable< - QueryFormatTypesAvailable extends string | Algebra, - SourceType, +export interface StringQueryable< SupportedMetadataType, - QueryType extends Query, - QueryStringContextType extends QueryStringContext, - QueryAlgebraContextType extends QueryAlgebraContext, + QueryStringContextType extends QueryStringContext = QueryStringContext, > { /** - * Initiate a given query. + * Initiate a given query provided as a string. * * This will produce a future to a query result, which has to be executed to obtain the query results. * @@ -95,49 +86,72 @@ export interface Queryable< * * @see Query */ - query( - query: QueryFormatType, - context?: QueryFormatType extends string ? QueryStringContextType : QueryAlgebraContextType, - ): Promise; + query(query: string, context?: QueryStringContextType): Promise>; } /** - * SPARQL-constrained query interface. + * Generic query engine interfaces. + * It allow engines to return any type of result object for Algebra queries. + * @param AlgebraType The supported algebra types. + * @param SupportedMetadataType The allowed metadata types. + * @param QueryStringContextType Type of the algebra-based query context. + */ + export interface AlgebraQueryable< + AlgebraType, + SupportedMetadataType, + QueryAlgebraContextType extends QueryAlgebraContext = QueryAlgebraContext, +> { + /** + * Initiate a given query provided as an Algebra object. + * + * This will produce a future to a query result, which has to be executed to obtain the query results. + * + * This can reject given an unsupported or invalid query. + * + * @see Query + */ + query(query: AlgebraType, context?: QueryAlgebraContextType): Promise>; +} + +/** + * SPARQL-constrained query interface for queries provided as strings. * * This interface guarantees that result objects are of the expected type as defined by the SPARQL spec. */ -export type SparqlQueryable< - QueryFormatTypesAvailable extends string | Algebra, - SourceType, - QueryStringContextType extends QueryStringContext, - QueryAlgebraContextType extends QueryAlgebraContext, - SupportedResultType, -> = unknown +export type StringSparqlQueryable = unknown & (SupportedResultType extends BindingsResultSupport ? { - queryBindings( - query: QueryFormatType, - context?: QueryFormatType extends string ? QueryStringContextType : QueryAlgebraContextType, - ): Promise>; + queryBindings(query: string, context?: QueryStringContextType): Promise>; } : unknown) & (SupportedResultType extends BooleanResultSupport ? { - queryBoolean( - query: QueryFormatType, - context?: QueryFormatType extends string ? QueryStringContextType : QueryAlgebraContextType, - ): Promise; + queryBoolean(query: string, context?: QueryStringContextType): Promise; } : unknown) & (SupportedResultType extends QuadsResultSupport ? { - queryQuads( - query: QueryFormatType, - context?: QueryFormatType extends string ? QueryStringContextType : QueryAlgebraContextType, - ): Promise>; + queryQuads(query: string, context?: QueryStringContextType): Promise>; } : unknown) & (SupportedResultType extends VoidResultSupport ? { - queryVoid( - query: QueryFormatType, - context?: QueryFormatType extends string ? QueryStringContextType : QueryAlgebraContextType, - ): Promise; + queryVoid(query: string, context?: QueryStringContextType): Promise; +} : unknown) +; + +/** + * SPARQL-constrainted query interface for queries provided as Algebra objects. + * + * This interface guarantees that result objects are of the expected type as defined by the SPARQL spec. + */ + export type AlgebraSparqlQueryable = unknown + & (SupportedResultType extends BindingsResultSupport ? { + queryBindings(query: AlgebraType, context?: QueryAlgebraContextType): Promise>; +} : unknown) + & (SupportedResultType extends BooleanResultSupport ? { + queryBoolean(query: AlgebraType, context?: QueryAlgebraContextType): Promise; +} : unknown) + & (SupportedResultType extends QuadsResultSupport ? { + queryQuads(query: AlgebraType, context?: QueryAlgebraContextType): Promise>; +} : unknown) + & (SupportedResultType extends VoidResultSupport ? { + queryVoid(query: AlgebraType, context?: QueryAlgebraContextType): Promise; } : unknown) - ; +; export type SparqlResultSupport = BindingsResultSupport & VoidResultSupport & QuadsResultSupport & BooleanResultSupport; export type BindingsResultSupport = { bindings: true }; diff --git a/rdf-js-query-tests.ts b/rdf-js-query-tests.ts index 4e02ebc..fc67df0 100644 --- a/rdf-js-query-tests.ts +++ b/rdf-js-query-tests.ts @@ -4,12 +4,21 @@ import { BindingsFactory, Bindings, Term, - Queryable, + StringQueryable, + AlgebraQueryable, SparqlResultSupport, MetadataOpts, QueryStringContext, QueryAlgebraContext, - AllMetadataSupport, Query, Variable, ResultStream, Quad, SparqlQueryable, BindingsResultSupport, QuadsResultSupport + AllMetadataSupport, + Query, + Variable, + ResultStream, + Quad, + StringSparqlQueryable, + AlgebraSparqlQueryable, + BindingsResultSupport, + QuadsResultSupport, } from "."; function test_bindings() { @@ -38,8 +47,8 @@ function test_bindings() { } } -async function test_queryable() { - const engine: Queryable, QueryStringContext, QueryAlgebraContext> = {}; +async function test_stringqueryable() { + const engine: StringQueryable = {}; const query: Query = await engine.query('SELECT * WHERE { ... }'); switch (query.resultType) { @@ -61,8 +70,8 @@ async function test_queryable() { } } -async function test_sparqlqueryable() { - const engine: SparqlQueryable, QueryAlgebraContext, SparqlResultSupport> = {}; +async function test_stringsparqlqueryable() { + const engine: StringSparqlQueryable = {}; const bindings: ResultStream = await engine.queryBindings('SELECT * WHERE { ... }'); const quads: ResultStream = await engine.queryQuads('CONSTRUCT WHERE { ... }'); @@ -70,8 +79,21 @@ async function test_sparqlqueryable() { const done: void = await engine.queryVoid('INSERT WHERE { ... }'); } -async function test_sparqlqueryable_partial() { - const engine: SparqlQueryable, QueryAlgebraContext, BindingsResultSupport & QuadsResultSupport> = {}; +async function test_algebrasparqlqueryable() { + interface AlgebraType { mock: 'algebra' } + const engine: AlgebraSparqlQueryable = {}; + + const bindings: ResultStream = await engine.queryBindings({ mock: 'algebra' }); + const quads: ResultStream = await engine.queryQuads({ mock: 'algebra' }); + const bool: boolean = await engine.queryBoolean({ mock: 'algebra' }); + const done: void = await engine.queryVoid({ mock: 'algebra' }); + + // @ts-ignore + await engine.queryBoolean('ASK WHERE { ... }'); // Query type doesn't match AlgebraType +} + +async function test_stringsparqlqueryable_partial() { + const engine: StringSparqlQueryable = {}; const bindings: ResultStream = await engine.queryBindings('SELECT * WHERE { ... }'); const quads: ResultStream = await engine.queryQuads('CONSTRUCT WHERE { ... }'); @@ -80,3 +102,15 @@ async function test_sparqlqueryable_partial() { // @ts-ignore const done: void = await engine.queryVoid('INSERT WHERE { ... }'); // Unsupported } + +async function test_algebrasparqlqueryable_partial() { + interface AlgebraType { mock: 'algebra' } + const engine: AlgebraSparqlQueryable = {}; + + const bindings: ResultStream = await engine.queryBindings({ mock: 'algebra' }); + const quads: ResultStream = await engine.queryQuads({ mock: 'algebra' }); + // @ts-ignore + const bool: boolean = await engine.queryBoolean({ mock: 'algebra' }); // Unsupported + // @ts-ignore + const done: void = await engine.queryVoid({ mock: 'algebra' }); // Unsupported +}