add toAst docs and sanity

Author: jitsedesmet

packages/algebra-transformer-1-1/lib/index.ts

@@ -1,7 +1,7 @@
 import * as Algebra from './algebra';
 import Factory from './factory';
 import translate from './toAlgebra';
-import { toSparql } from './toAst/sparql';
+import { toSparql } from './toAst/toAst';
 import Util from './util';
 
 export { translate, Algebra, Factory, toSparql, Util };

packages/algebra-transformer-1-1/lib/toAlgebra/core.ts

@@ -50,6 +50,6 @@ export function isTriple(triple: any): triple is RDF.Quad {
   return triple.subject && triple.predicate && triple.object;
 }
 
-export function isVariable(term: any): term is RDF.Variable {
+export function isVariable(term: RDF.Term): term is RDF.Variable {
   return term?.termType === 'Variable';
 }

packages/algebra-transformer-1-1/lib/toAst/aggregate.ts

@@ -6,10 +6,25 @@ import * as Algebra from '../algebra';
 import Factory from '../factory';
 
 export interface AstContext {
+  /**
+   * Whether we are contained in a projection
+   */
   project: boolean;
+  /**
+   * All extends found in our suboperations
+   */
   extend: Algebra.Extend[];
+  /**
+   * All groups found in our suboperations
+   */
   group: RDF.Variable[];
+  /**
+   * All aggregates found in our suboperations
+   */
   aggregates: Algebra.BoundAggregate[];
+  /**
+   * All orderings found in our suboperations
+   */
   order: Algebra.Expression[];
   factory: Factory;
   astFactory: AstFactory;

packages/algebra-transformer-1-1/lib/toAst/core.ts

@@ -32,6 +32,7 @@ export function translateExistenceExpression(
   const F = c.astFactory;
   return F.expressionPatternOperation(
     expr.not ? 'notexists' : 'exists',
+    // TranslateOperation can give an array
     F.patternGroup(Util.flatten([ translateOperation(c, expr.input) ]), F.gen()),
     F.gen(),
   );
@@ -63,13 +64,12 @@ export function translateOperatorExpression(
   );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-export function translateWildcardExpression(c: AstContext, expr: Algebra.WildcardExpression): Wildcard {
+export function translateWildcardExpression(c: AstContext, _expr: Algebra.WildcardExpression): Wildcard {
   const F = c.astFactory;
   return F.wildcard(F.gen());
 }
 
-export function arrayToPattern(c: AstContext, input: Pattern[]): PatternGroup {
+export function wrapInPatternGroup(c: AstContext, input: Pattern[] | Pattern): PatternGroup {
   const F = c.astFactory;
   if (!Array.isArray(input)) {
     return F.patternGroup([ input ], F.gen());

packages/algebra-transformer-1-1/lib/toAst/expression.ts

@@ -2,17 +2,17 @@ import type * as RDF from '@rdfjs/types';
 import type {
   DatasetClauses,
   Pattern,
-  PatternBgp,
+  PatternGroup,
+  QuerySelect,
   TermBlank,
   TermIri,
   TermLiteral,
   TermVariable,
   TripleNesting,
 } from '@traqula/rules-sparql-1-1';
-import type * as Algebra from '../algebra';
+import type { Algebra } from '../index';
 import Util from '../util';
 import type { AstContext } from './core';
-import { translatePathComponent } from './path';
 import { translateExpression, translateOperation } from './pattern';
 
 type RdfTermToAst<T extends RDF.Term> = T extends RDF.Variable ? TermVariable :
@@ -41,6 +41,12 @@ export function translateTerm<T extends RDF.Term>(c: AstContext, term: T): RdfTe
   throw new Error(`invalid term type: ${term.termType}`);
 }
 
+/**
+ * Extend is for example a bind, or an aggregator.
+ * The result is thus registered to be tackled at the project level,
+ *  or if we are not in project scope, we give it as a patternBind
+ *  - of course, the pattern bind is scoped with the other operations at this level
+ */
 export function translateExtend(c: AstContext, op: Algebra.Extend): Pattern[] {
   const F = c.astFactory;
   if (c.project) {
@@ -69,22 +75,14 @@ export function translateDatasetClauses(
   ], F.gen());
 }
 
-export function translateOrderBy(c: AstContext, op: Algebra.OrderBy): any {
+/**
+ * An order by is just registered to be handled in the creation of your QueryBase
+ */
+export function translateOrderBy(c: AstContext, op: Algebra.OrderBy): ReturnType<typeof translateOperation> {
   c.order.push(...op.expressions);
   return translateOperation(c, op.input);
 }
 
-export function translatePath(c: AstContext, op: Algebra.Path): PatternBgp {
-  const F = c.astFactory;
-  return F.patternBgp([
-    F.triple(
-      translateTerm(c, op.subject),
-      translatePathComponent(c, op.predicate),
-      translateTerm(c, op.object),
-    ),
-  ], F.gen());
-}
-
 export function translatePattern(c: AstContext, op: Algebra.Pattern): TripleNesting {
   const F = c.astFactory;
   return F.triple(
@@ -94,9 +92,22 @@ export function translatePattern(c: AstContext, op: Algebra.Pattern): TripleNest
   );
 }
 
-export function translateReduced(c: AstContext, op: Algebra.Reduced): Pattern {
-  const result = translateOperation(c, op.input);
-  // Project is nested in group object
-  result.patterns[0].reduced = true;
+/**
+ * Reduced is wrapped around a project, set the query contained to be distinct
+ */
+export function translateReduced(c: AstContext, op: Algebra.Reduced): PatternGroup {
+  const result: PatternGroup = translateOperation(c, op.input);
+  const select = <QuerySelect>result.patterns[0];
+  select.reduced = true;
+  return result;
+}
+
+/**
+ * District is wrapped around a project, set the query contained to be distinct
+ */
+export function translateDistinct(c: AstContext, op: Algebra.Distinct): PatternGroup {
+  const result: PatternGroup = translateOperation(c, op.input);
+  const select = <QuerySelect>result.patterns[0];
+  select.distinct = true;
   return result;
 }

packages/algebra-transformer-1-1/lib/toAst/general.ts

@@ -5,10 +5,11 @@ import type {
   PathModified,
   PathNegatedElt,
   PathPure,
+  PatternBgp,
   PropertyPathChain,
   TermIri,
 } from '@traqula/rules-sparql-1-1';
-import type { Algebra } from '../index';
+import type * as Algebra from '../algebra';
 import { types } from '../toAlgebra/core';
 import Util from '../util';
 import type { AstContext } from './core';
@@ -29,7 +30,7 @@ export function translatePathComponent(c: AstContext, path: Algebra.Operation):
   }
 }
 
-export function translateAlt(c: AstContext, path: Algebra.Alt): any {
+export function translateAlt(c: AstContext, path: Algebra.Alt): Path {
   const F = c.astFactory;
   const mapped = path.input.map(x => translatePathComponent(c, x));
   if (mapped.every(entry => F.isPathOfType(entry, [ '!' ]))) {
@@ -104,3 +105,14 @@ export function translateZeroOrOnePath(c: AstContext, path: Algebra.ZeroOrOnePat
   const F = c.astFactory;
   return F.path('?', [ translatePathComponent(c, path.path) ], F.gen());
 }
+
+export function translatePath(c: AstContext, op: Algebra.Path): PatternBgp {
+  const F = c.astFactory;
+  return F.patternBgp([
+    F.triple(
+      translateTerm(c, op.subject),
+      translatePathComponent(c, op.predicate),
+      translateTerm(c, op.object),
+    ),
+  ], F.gen());
+}