@comunica/utils-expression-evaluator 3.2.4-alpha.47.0

package/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright © 2017–now Ruben Taelman, Joachim Van Herwegen
+Comunica Association and Ghent University – imec, Belgium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Comunica Expression Evaluator
+
+[![npm version](https://badge.fury.io/js/%40comunica%2Fexpression-evaluator.svg)](https://www.npmjs.com/package/@comunica/expression-evaluator)
+
+Previously called sparqlee - sparql expression evaluator. A simple spec-compliant SPARQL 1.1 expression evaluator package.
+
+**[Learn more about the expression evaluator](https://comunica.dev/docs/modify/advanced/expression-evaluator/).**
+
+This module is part of the [Comunica framework](https://github.com/comunica/comunica),
+and should only be used by [developers that want to build their own query engine](https://comunica.dev/docs/modify/).
+
+[Click here if you just want to query with Comunica](https://comunica.dev/docs/query/).
+
+## Install
+
+```bash
+$ yarn add @comunica/utils-expression-evaluator
+```
+
+## Exposed classes
+
+* [`ExpressionEvaluator`](https://comunica.github.io/comunica/classes/_comunica_expression_evaluator.AsyncEvaluator.html): An evaluator for SPARQL expressions working with Promises.
+* [`IAsyncEvaluatorContext`](https://comunica.github.io/comunica/classes/_comunica_expression_evaluator.IAsyncEvaluatorContext.html): Context used to configure the `ExpressionEvaluator`. See [Config](https://comunica.dev/docs/modify/advanced/expression-evaluator/#config).
+* [`SyncEvaluator`](https://comunica.github.io/comunica/classes/_comunica_expression_evaluator.SyncEvaluator.html): An evaluator for SPARQL expressions working without Promises.
+* [`ISyncEvaluatorContext`](https://comunica.github.io/comunica/interfaces/_comunica_expression_evaluator.ISyncEvaluatorContext.html): Context used to configure the `SyncEvaluator`. See [Config](https://comunica.dev/docs/modify/advanced/expression-evaluator/#config).
+* [`AggregateEvaluator`](https://comunica.github.io/comunica/classes/_comunica_expression_evaluator.AggregateEvaluator.html): An evaluator for SPARQL aggregate expressions working without promises. See [Aggregates](https://comunica.dev/docs/modify/advanced/expression-evaluator/#aggregates).
+* [`ExpressionError`](https://comunica.github.io/comunica/classes/_comunica_expression_evaluator.ExpressionError.html): An error class for SPARQL expression errors as defined in the [error section](https://comunica.dev/docs/modify/advanced/expression-evaluator/#errors).
+* [`isExpressionError`](https://comunica.github.io/comunica/functions/_comunica_expression_evaluator.isExpressionError.html): A way to check if an error is of type `ExpressionError`.
+* [`orderTypes`](https://comunica.github.io/comunica/functions/_comunica_expression_evaluator.orderTypes.html): A function to order types according to the [SPARQL ORDER BY specification](https://www.w3.org/TR/sparql11-query/#modOrderBy).
+* [`AsyncAggregateEvaluator`](https://comunica.github.io/comunica/classes/_comunica_expression_evaluator.AsyncAggregateEvaluator.html): An evaluator for SPARQL aggregate expressions working with promises. See [Aggregates](https://comunica.dev/docs/modify/advanced/expression-evaluator/#aggregates).
+
+## Development
+
+## Setup locally
+
+1. Install `yarn` and `node`.
+2. Run `yarn install`.
+3. Use these evident commands (or check `package.json`):
+    - building once: `yarn run build`
+
+### Layout and control flow
+
+SPARQL Algebra expression can be transformed to an internal representation (see [AlgebraTransformer.ts](../actor-expression-evaluator-factory-default/lib/AlgebraTransformer.ts)).
+This will build objects (see [expressions module](./lib/expressions)) that contain all the logic and data for evaluation.
+After transformation, the evaluator will recursively evaluate all the expressions.
+
+### Testing
+
+The testing environment is set up to do a lot of tests with little code.
+The files responsible for fluent behaviour reside in the [`test/util`](./test/util) module.
+Most tests can be run by running the `runTestTable` method in [utils](test/util/utils.ts).
+This method expects a TestTable. Multiple test are run over a TestTable (one for every line).
+A TestTable may contain aliases if the aliases are also provided
+(Some handy aliases reside in [Aliases.ts](test/util/Aliases.ts)).
+This means that when testing something like `"3"^^xsd:integer equals "3"^^xsd:integer` is `"true"^^xsd:boolean`.
+We would write a small table (for this example some more tests are added) and test it like this:
+```js
+import { bool, merge, numeric } from './util/Aliases';
+import { Notation } from './util/TruthTable';
+import { runTestTable } from './util/utils';
+runTestTable({
+  testTable: `
+       3i 3i = true
+       3i -5i = false
+       -0f 0f = true
+       NaN  NaN = false
+   `,
+  arity: 2,
+  operation: '=',
+  aliases: merge(numeric, bool),
+  notation: Notation.Infix,
+});
+```
+More options can be provided and are explained with the type definition of the argument of `runTestTable`.
+
+We can also provide an `errorTable` to the `runTestTable` method.
+This is used when we want to test if calling certain functions on certain arguments throws the error we want.
+An example is testing whether `Unknown named operator` error is thrown when
+we don't provide the implementation for an extension function.
+```js
+import { bool, merge, numeric } from './util/Aliases';
+import { Notation } from './util/TruthTable';
+import { runTestTable } from './util/utils';
+runTestTable({
+  errorTable: `
+       3i 3i = 'Unknown named operator'
+       3i -5i = 'Unknown named operator'
+       -0f 0f = 'Unknown named operator'
+       NaN  NaN = 'Unknown named operator'
+   `,
+  arity: 2,
+  operation: '<https://example.org/functions#equal>',
+  aliases: merge(numeric, bool),
+  notation: Notation.Infix,
+});
+```
+When you don't care what the error is, you can just test for `''`.
+
+In case the tables are too restrictive for your test, and you need an evaluation.
+You should still use the `generalEvaluate` function from [generalEvaluation.ts](test/util/generalEvaluation.ts).
+This function will automatically run both async and sync when possible.
+This increases your tests' coverage.

package/lib/expressions/Aggregate.d.ts

@@ -0,0 +1,9 @@
+import type { AggregateExpression } from '@comunica/types';
+import { ExpressionType } from '@comunica/types';
+import type { Algebra as Alg } from 'sparqlalgebrajs';
+export declare class Aggregate implements AggregateExpression {
+    name: string;
+    expression: Alg.AggregateExpression;
+    expressionType: ExpressionType.Aggregate;
+    constructor(name: string, expression: Alg.AggregateExpression);
+}

package/lib/expressions/Aggregate.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Aggregate = void 0;
+const types_1 = require("@comunica/types");
+class Aggregate {
+    constructor(name, expression) {
+        this.name = name;
+        this.expression = expression;
+        this.expressionType = types_1.ExpressionType.Aggregate;
+    }
+}
+exports.Aggregate = Aggregate;
+//# sourceMappingURL=Aggregate.js.map

package/lib/expressions/Aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aggregate.js","sourceRoot":"","sources":["Aggregate.ts"],"names":[],"mappings":";;;AACA,2CAAiD;AAGjD,MAAa,SAAS;IAGpB,YACS,IAAY,EACZ,UAAmC;QADnC,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAyB;QAJrC,mBAAc,GAA6B,sBAAc,CAAC,SAAS,CAAC;IAKxE,CAAC;CACL;AAPD,8BAOC","sourcesContent":["import type { AggregateExpression } from '@comunica/types';\nimport { ExpressionType } from '@comunica/types';\nimport type { Algebra as Alg } from 'sparqlalgebrajs';\n\nexport class Aggregate implements AggregateExpression {\n  public expressionType: ExpressionType.Aggregate = ExpressionType.Aggregate;\n\n  public constructor(\n    public name: string,\n    public expression: Alg.AggregateExpression,\n  ) {}\n}\n"]}

package/lib/expressions/Existence.d.ts

@@ -0,0 +1,8 @@
+import type { ExistenceExpression } from '@comunica/types';
+import { ExpressionType } from '@comunica/types';
+import type { Algebra as Alg } from 'sparqlalgebrajs';
+export declare class Existence implements ExistenceExpression {
+    expression: Alg.ExistenceExpression;
+    expressionType: ExpressionType.Existence;
+    constructor(expression: Alg.ExistenceExpression);
+}

package/lib/expressions/Existence.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Existence = void 0;
+const types_1 = require("@comunica/types");
+class Existence {
+    constructor(expression) {
+        this.expression = expression;
+        this.expressionType = types_1.ExpressionType.Existence;
+    }
+}
+exports.Existence = Existence;
+//# sourceMappingURL=Existence.js.map

package/lib/expressions/Existence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Existence.js","sourceRoot":"","sources":["Existence.ts"],"names":[],"mappings":";;;AACA,2CAAiD;AAGjD,MAAa,SAAS;IAEpB,YAA0B,UAAmC;QAAnC,eAAU,GAAV,UAAU,CAAyB;QADtD,mBAAc,GAA6B,sBAAc,CAAC,SAAS,CAAC;IACX,CAAC;CAClE;AAHD,8BAGC","sourcesContent":["import type { ExistenceExpression } from '@comunica/types';\nimport { ExpressionType } from '@comunica/types';\nimport type { Algebra as Alg } from 'sparqlalgebrajs';\n\nexport class Existence implements ExistenceExpression {\n  public expressionType: ExpressionType.Existence = ExpressionType.Existence;\n  public constructor(public expression: Alg.ExistenceExpression) {}\n}\n"]}

package/lib/expressions/Expressions.d.ts

@@ -0,0 +1,2 @@
+import type { TermType } from '@comunica/types';
+export declare function asTermType(type: string): TermType | undefined;

package/lib/expressions/Expressions.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asTermType = void 0;
+function asTermType(type) {
+    if (type === 'namedNode' || type === 'literal' || type === 'blankNode' || type === 'quad') {
+        return type;
+    }
+    return undefined;
+}
+exports.asTermType = asTermType;
+//# sourceMappingURL=Expressions.js.map

package/lib/expressions/Expressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Expressions.js","sourceRoot":"","sources":["Expressions.ts"],"names":[],"mappings":";;;AAGA,SAAgB,UAAU,CAAC,IAAY;IACrC,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AALD,gCAKC","sourcesContent":["// TODO: Create alias Term = TermExpression\nimport type { TermType } from '@comunica/types';\n\nexport function asTermType(type: string): TermType | undefined {\n  if (type === 'namedNode' || type === 'literal' || type === 'blankNode' || type === 'quad') {\n    return type;\n  }\n  return undefined;\n}\n"]}

package/lib/expressions/Operator.d.ts

@@ -0,0 +1,9 @@
+import type { Expression, FunctionApplication, OperatorExpression } from '@comunica/types';
+import { ExpressionType } from '@comunica/types';
+export declare class Operator implements OperatorExpression {
+    name: string;
+    args: Expression[];
+    apply: FunctionApplication;
+    expressionType: ExpressionType.Operator;
+    constructor(name: string, args: Expression[], apply: FunctionApplication);
+}

package/lib/expressions/Operator.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Operator = void 0;
+const types_1 = require("@comunica/types");
+class Operator {
+    constructor(name, args, apply) {
+        this.name = name;
+        this.args = args;
+        this.apply = apply;
+        this.expressionType = types_1.ExpressionType.Operator;
+    }
+}
+exports.Operator = Operator;
+//# sourceMappingURL=Operator.js.map

package/lib/expressions/Operator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Operator.js","sourceRoot":"","sources":["Operator.ts"],"names":[],"mappings":";;;AACA,2CAAiD;AAEjD,MAAa,QAAQ;IAGnB,YAA0B,IAAY,EAAS,IAAkB,EAAS,KAA0B;QAA1E,SAAI,GAAJ,IAAI,CAAQ;QAAS,SAAI,GAAJ,IAAI,CAAc;QAAS,UAAK,GAAL,KAAK,CAAqB;QAF7F,mBAAc,GAA4B,sBAAc,CAAC,QAAQ,CAAC;IAE8B,CAAC;CACzG;AAJD,4BAIC","sourcesContent":["import type { Expression, FunctionApplication, OperatorExpression } from '@comunica/types';\nimport { ExpressionType } from '@comunica/types';\n\nexport class Operator implements OperatorExpression {\n  public expressionType: ExpressionType.Operator = ExpressionType.Operator;\n\n  public constructor(public name: string, public args: Expression[], public apply: FunctionApplication) {}\n}\n"]}

package/lib/expressions/Term.d.ts

@@ -0,0 +1,180 @@
+import type { ComunicaDataFactory, IDateRepresentation, IDateTimeRepresentation, IDurationRepresentation, ISuperTypeProvider, ITimeRepresentation, IYearMonthDurationRepresentation, TermExpression, TermType } from '@comunica/types';
+import { ExpressionType } from '@comunica/types';
+import type * as RDF from '@rdfjs/types';
+export declare abstract class Term implements TermExpression {
+    expressionType: ExpressionType.Term;
+    abstract termType: TermType;
+    abstract toRDF(dataFactory: ComunicaDataFactory): RDF.Term;
+    str(): string;
+    coerceEBV(): boolean;
+}
+export declare class NamedNode extends Term {
+    value: string;
+    termType: TermType;
+    constructor(value: string);
+    toRDF(dataFactory: ComunicaDataFactory): RDF.Term;
+    str(): string;
+}
+export declare class BlankNode extends Term {
+    value: RDF.BlankNode | string;
+    termType: TermType;
+    constructor(value: RDF.BlankNode | string);
+    toRDF(dataFactory: ComunicaDataFactory): RDF.Term;
+}
+export declare class Quad extends Term {
+    readonly subject: Term;
+    readonly predicate: Term;
+    readonly object: Term;
+    readonly graph: Term;
+    termType: TermType;
+    constructor(subject: Term, predicate: Term, object: Term, graph: Term);
+    toRDF(dataFactory: ComunicaDataFactory): RDF.BaseQuad;
+    str(): string;
+}
+export declare class DefaultGraph extends Term {
+    termType: TermType;
+    constructor();
+    toRDF(dataFactory: ComunicaDataFactory): RDF.DefaultGraph;
+    str(): string;
+}
+export declare function isLiteralTermExpression(expr: TermExpression): Literal<any> | undefined;
+export interface ISerializable {
+    toString: () => string;
+}
+export declare class Literal<T extends ISerializable> extends Term {
+    typedValue: T;
+    dataType: string;
+    strValue?: string | undefined;
+    language?: string | undefined;
+    termType: "literal";
+    /**
+     * @param typedValue internal representation of this literal's value
+     * @param dataType a string representing the datatype. Can be of type @see LiteralTypes or any URI
+     * @param strValue the string value of this literal. In other words, the string representing the RDF.literal value.
+     * @param language the language, mainly for language enabled strings like RDF_LANG_STRING
+     */
+    constructor(typedValue: T, dataType: string, strValue?: string | undefined, language?: string | undefined);
+    toRDF(dataFactory: ComunicaDataFactory): RDF.Literal;
+    str(): string;
+}
+export declare abstract class NumericLiteral extends Literal<number> {
+    typedValue: number;
+    strValue?: string | undefined;
+    language?: string | undefined;
+    protected constructor(typedValue: number, dataType: string, strValue?: string | undefined, language?: string | undefined);
+    protected abstract specificFormatter(val: number): string;
+    coerceEBV(): boolean;
+    toRDF(dataFactory: ComunicaDataFactory): RDF.Literal;
+    str(): string;
+}
+export declare class IntegerLiteral extends NumericLiteral {
+    typedValue: number;
+    strValue?: string | undefined;
+    language?: string | undefined;
+    constructor(typedValue: number, dataType?: string, strValue?: string | undefined, language?: string | undefined);
+    protected specificFormatter(val: number): string;
+}
+export declare class DecimalLiteral extends NumericLiteral {
+    typedValue: number;
+    strValue?: string | undefined;
+    language?: string | undefined;
+    constructor(typedValue: number, dataType?: string, strValue?: string | undefined, language?: string | undefined);
+    protected specificFormatter(val: number): string;
+}
+export declare class FloatLiteral extends NumericLiteral {
+    typedValue: number;
+    strValue?: string | undefined;
+    language?: string | undefined;
+    constructor(typedValue: number, dataType?: string, strValue?: string | undefined, language?: string | undefined);
+    protected specificFormatter(val: number): string;
+}
+export declare class DoubleLiteral extends NumericLiteral {
+    typedValue: number;
+    strValue?: string | undefined;
+    language?: string | undefined;
+    constructor(typedValue: number, dataType?: string, strValue?: string | undefined, language?: string | undefined);
+    protected specificFormatter(val: number): string;
+}
+export declare class BooleanLiteral extends Literal<boolean> {
+    typedValue: boolean;
+    strValue?: string | undefined;
+    constructor(typedValue: boolean, strValue?: string | undefined, dataType?: string);
+    coerceEBV(): boolean;
+}
+export declare class LangStringLiteral extends Literal<string> {
+    typedValue: string;
+    language: string;
+    constructor(typedValue: string, language: string, dataType?: string);
+    coerceEBV(): boolean;
+}
+export declare class StringLiteral extends Literal<string> {
+    typedValue: string;
+    /**
+     * @param typedValue
+     * @param dataType Should be type that implements XSD_STRING
+     */
+    constructor(typedValue: string, dataType?: string);
+    coerceEBV(): boolean;
+}
+export declare class DateTimeLiteral extends Literal<IDateTimeRepresentation> {
+    typedValue: IDateTimeRepresentation;
+    strValue?: string | undefined;
+    constructor(typedValue: IDateTimeRepresentation, strValue?: string | undefined, dataType?: string);
+    str(): string;
+}
+export declare class TimeLiteral extends Literal<ITimeRepresentation> {
+    typedValue: ITimeRepresentation;
+    strValue?: string | undefined;
+    constructor(typedValue: ITimeRepresentation, strValue?: string | undefined, dataType?: string);
+    str(): string;
+}
+export declare class DateLiteral extends Literal<IDateRepresentation> {
+    typedValue: IDateRepresentation;
+    strValue?: string | undefined;
+    constructor(typedValue: IDateRepresentation, strValue?: string | undefined, dataType?: string);
+    str(): string;
+}
+export declare class DurationLiteral extends Literal<Partial<IDurationRepresentation>> {
+    typedValue: Partial<IDurationRepresentation>;
+    strValue?: string | undefined;
+    constructor(typedValue: Partial<IDurationRepresentation>, strValue?: string | undefined, dataType?: string);
+    str(): string;
+}
+export declare class DayTimeDurationLiteral extends DurationLiteral {
+    typedValue: Partial<IDurationRepresentation>;
+    strValue?: string | undefined;
+    constructor(typedValue: Partial<IDurationRepresentation>, strValue?: string | undefined, dataType?: string);
+}
+export declare class YearMonthDurationLiteral extends Literal<Partial<IYearMonthDurationRepresentation>> {
+    typedValue: Partial<IYearMonthDurationRepresentation>;
+    strValue?: string | undefined;
+    constructor(typedValue: Partial<IYearMonthDurationRepresentation>, strValue?: string | undefined, dataType?: string);
+    str(): string;
+}
+/**
+ * This class is used when a literal is parsed, and it's value is
+ * an invalid lexical form for it's datatype. The spec defines value with
+ * invalid lexical form are still valid terms, and as such we can not error
+ * immediately. This class makes sure that the typedValue will remain undefined,
+ * and the category 'nonlexical'. This way, only when operators apply to the
+ * 'nonlexical' category, they will keep working, otherwise they will throw a
+ * type error.
+ * This seems to match the spec, except maybe for functions that accept
+ * non-lexical values for their datatype.
+ *
+ * See:
+ *  - https://www.w3.org/TR/xquery/#dt-type-error
+ *  - https://www.w3.org/TR/rdf-concepts/#section-Literal-Value
+ *  - https://www.w3.org/TR/xquery/#dt-ebv
+ *  - ... some other more precise thing i can't find...
+ */
+export declare class NonLexicalLiteral extends Literal<{
+    toString: () => 'undefined';
+}> {
+    private readonly openWorldType;
+    constructor(typedValue: undefined, dataType: string, openWorldType: ISuperTypeProvider, strValue?: string, language?: string);
+    coerceEBV(): boolean;
+    toRDF(dataFactory: ComunicaDataFactory): RDF.Literal;
+    str(): string;
+}
+export declare function isNonLexicalLiteral(lit: Literal<any>): NonLexicalLiteral | undefined;