@cubicweb/client 3.0.0-alpha.11 → 3.0.0-alpha.14

package/src/api/Api.ts

@@ -1,46 +1,35 @@
-import { ValidationError } from "../Errors.js";
+import { ValidationError } from "../errors.js";
 import { RawSchema } from "../schema/raw/Schema.js";
-import {
-  TransactionResult,
-  Transaction,
-  TransactionQueryScalarRef,
-  TransactionQueryBinaryRef,
-} from "./Transaction.js";
+import { getBinariesFromTransaction, serializeQueryParams } from "../utils.js";
+import { ResultSet, ResultSetCell } from "./ResultSet.js";
+import { RQLBinary } from "./binary/RQLBinary.js";
+import { RQLQueryCellRef } from "./query/references.js";
+import { Transaction } from "./transaction/Transaction.js";
+import { TransactionResult } from "./transaction/TransactionResult.js";
 
 /**
- * Type representing an RQL request and its associated parameters.
+ * Type representing valid final values to use as parameters in a RQL query.
+ *
+ * For references to requests/binaries, see {@link RQLQueryCellRef} and {@link RQLQueryBinaryRef}
  *
  * @category Api
  */
-export type RQLQuery = [string, RQLParams];
+export type RQLQueryParamValue = string | number | boolean | null;
 
-export type RQLParamValue = string | number | boolean | null;
 /**
  * Type representing RQL parameters to send along a request.
  *
+ * Each key must be referenced in the RQL query.
+ *
  * @category Api
  */
-export type RQLParams = Record<
+export type RQLQueryParams = Record<
   string,
-  RQLParamValue | TransactionQueryScalarRef | TransactionQueryBinaryRef
+  RQLQueryParamValue | RQLQueryCellRef | RQLBinary
 >;
 
 /**
- * Type representing a row returned in a result set.
- *
- * @category Api
- */
-export type RqlRow = Array<string | number | boolean | null>;
-
-/**
- * Type representing a RQL request result.
- *
- * @category Api
- */
-export type ResultSet = Array<RqlRow>;
-
-/**
- * Type representing the currently logged user's data
+ * Type representing the currently logged user's data as returned by the `/current-user` route
  *
  * @category Api
  */
@@ -64,17 +53,24 @@ type ApiError = {
 /**
  * Type representing the error data sent to clients when retrieving an API error.
  *
+ * It simply adds the HTTP status code in a `status` key to the regular CubicWeb api error,
+ * so users can handle HTTP status codes in their code.
+ *
  * @category Api
  */
 export type ApiErrorResponse = {
   status: number;
 } & ApiError;
 
+type RawTransactionResult = ReadonlyArray<
+  ReadonlyArray<ReadonlyArray<ResultSetCell>>
+>;
+
 /**
  * Class used to handle requests to the CubicWeb API.
  *
  * You should never have to create this object yourself.
- * Instead, retrieve this object from the methods in the `Client` class.
+ * Instead, retrieve this object from the methods in the {@link Client} class.
  *
  * @internal
  */
@@ -92,7 +88,7 @@ export default class Api {
    * Class used to handle requests to the CubicWeb API.
    *
    * You should never have to create this object yourself.
-   * Instead, retrieve this object from the methods in the `Client` class.
+   * Instead, retrieve this object from the methods in the {@link Client} class.
    *
    * @param apiUrl The API url. It should not include the API version as it will be automatically added.
    * Example: if you can retrieve the schema with https://example.com/api/v1/schema,
@@ -132,7 +128,7 @@ export default class Api {
    * Tries to log in the user on the configured CubicWeb instance with the given credentials.
    *
    * @param login The user login
-   * @param password THe user password
+   * @param password The user password
    * @returns A promise returning true if the login was successful, false otherwise
    */
   async login(login: string, password: string): Promise<boolean> {
@@ -178,7 +174,9 @@ export default class Api {
   /**
    * Get the binary for the given entity attribute
    *
-   * @returns A promise resolving to the binary
+   * @param eid Entity eid to fetch the binary from
+   * @param attribute Attribute on the entity in which the binary is stored
+   * @returns A promise resolving to the binary as a Blob
    */
   async binary(eid: number, attribute: string): Promise<Blob> {
     const params = new URLSearchParams({
@@ -191,10 +189,20 @@ export default class Api {
     });
   }
 
+  /**
+   * Executes the given transaction.
+   *
+   * If the {@link Transaction} object contains binaries, the request is automatically
+   * sent using `multipart/form-data` to allow uploading binaries.
+   *
+   * @param transaction Transaction to execute
+   * @returns A promise returning the transaction result on success
+   */
   async rql(transaction: Transaction): Promise<TransactionResult> {
+    const binaries = getBinariesFromTransaction(transaction);
     try {
-      if (Object.keys(transaction.binaries).length > 0) {
-        return await this.multipartTransaction(transaction);
+      if (binaries.length > 0) {
+        return await this.multipartTransaction(transaction, binaries);
       } else {
         return await this.jsonTransaction(transaction);
       }
@@ -204,21 +212,24 @@ export default class Api {
   }
 
   private getTransactionParams(transaction: Transaction) {
-    return transaction.queries.map((transactionQuery) => ({
-      query: transactionQuery.query,
-      params: transactionQuery.params,
+    return transaction.queries.map((rqlQuery) => ({
+      query: rqlQuery.rql,
+      params: serializeQueryParams(transaction, rqlQuery.params),
     }));
   }
 
-  private async multipartTransaction(transaction: Transaction) {
+  private async multipartTransaction(
+    transaction: Transaction,
+    binaries: RQLBinary[]
+  ) {
     const jsonParams = this.getTransactionParams(transaction);
     const formData = new FormData();
     formData.append("queries", JSON.stringify(jsonParams));
-    Object.entries(transaction.binaries).forEach(([key, value]) => {
-      formData.append(key, value);
+    binaries.forEach((binary) => {
+      formData.append(binary.uuid, binary.blob);
     });
 
-    const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
+    const resultSets = await nonNullFetchApi<RawTransactionResult>(
       this._rqlApiUrl,
       {
         method: "POST",
@@ -226,11 +237,14 @@ export default class Api {
         body: formData,
       }
     );
-    return new TransactionResult(resultSets);
+    return new TransactionResult(
+      transaction,
+      resultSets.map((r) => new ResultSet(r))
+    );
   }
 
   private async jsonTransaction(transaction: Transaction) {
-    const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
+    const resultSets = await nonNullFetchApi<RawTransactionResult>(
       this._rqlApiUrl,
       {
         method: "POST",
@@ -238,7 +252,10 @@ export default class Api {
         body: JSON.stringify(this.getTransactionParams(transaction)),
       }
     );
-    return new TransactionResult(resultSets);
+    return new TransactionResult(
+      transaction,
+      resultSets.map((r) => new ResultSet(r))
+    );
   }
 
   private handleUserErrors(error: unknown): never {

package/src/api/Client.ts

@@ -1,10 +1,9 @@
 import { Schema } from "../schema/classes/Schema.js";
-import Api, { RQLParams, ResultSet, CurrentUser } from "./Api.js";
-import {
-  BinariesParam,
-  Transaction,
-  TransactionResult,
-} from "./Transaction.js";
+import Api, { RQLQueryParams, CurrentUser } from "./Api.js";
+import { ResultSet } from "./ResultSet.js";
+import { RQLQuery } from "./query/RQLQuery.js";
+import { Transaction } from "./transaction/Transaction.js";
+import { TransactionResult } from "./transaction/TransactionResult.js";
 
 /**
  * Class used to communicate with a CubicWeb instance's API.
@@ -32,20 +31,19 @@ export default class Client {
   /**
    * Executes the given query and waits for the response.
    *
-   * @param query The RQL query to send
+   * If binaries are given, the request is automatically
+   * sent using `multipart/form-data` to allow uploading binaries.
+   *
+   * @param rql The RQL query to send
    * @param params The additional parameters for the request
    * @returns A promise with the request's result set
    */
-  async execute(
-    query: string,
-    params: RQLParams = {},
-    binaries?: BinariesParam
-  ): Promise<ResultSet> {
+  async execute(rql: string, params: RQLQueryParams = {}): Promise<ResultSet> {
     const transaction = new Transaction();
-    const transactionQuery = transaction.push(query, params);
-    transaction.setBinaries(binaries);
+    const query = new RQLQuery(rql, params);
+    transaction.push(query);
     const result = await this.executeTransaction(transaction);
-    return result.resolveQuery(transactionQuery.ref());
+    return result.getResultSet(query);
   }
 
   /**
@@ -62,7 +60,7 @@ export default class Client {
    * Tries to log in the user on the configured CubicWeb instance with the given credentials.
    *
    * @param login The user login
-   * @param password THe user password
+   * @param password The user password
    * @returns A promise returning true if the login was successful, false otherwise
    */
   async login(login: string, password: string) {
@@ -88,8 +86,13 @@ export default class Client {
   }
 
   /**
+   * Executes the given transaction.
+   *
+   * If the {@link Transaction} object contains binaries, the request is automatically
+   * sent using `multipart/form-data` to allow uploading binaries.
+   *
    * @param transaction Transaction to execute
-   * @returns A promise fulfilled when the transaction is completed
+   * @returns A promise returning the transaction result on success
    */
   async executeTransaction(
     transaction: Transaction
@@ -100,7 +103,9 @@ export default class Client {
   /**
    * Get the binary for the given entity attribute
    *
-   * @returns A promise resolving to the binary
+   * @param eid Entity eid to fetch the binary from
+   * @param attribute Attribute on the entity in which the binary is stored
+   * @returns A promise resolving to the binary as a Blob
    */
   async getBinary(eid: number, attribute: string) {
     return await this.api.binary(eid, attribute);

package/src/api/ResultSet.ts

@@ -0,0 +1,29 @@
+/**
+ * Type representing a final value in a result set.
+ *
+ * Please not this type may not be accurate if you use entity methods,
+ * as those methods may return any data structure.
+ *
+ * @category Api
+ */
+export type ResultSetCell = string | number | boolean | null;
+
+/**
+ * Type representing a row returned in a result set.
+ *
+ * @category Api
+ */
+export type ResultSetRow<
+  T extends ReadonlyArray<ResultSetCell> = ReadonlyArray<ResultSetCell>
+> = T;
+
+/**
+ * Class representing a RQL request result.
+ *
+ * @category Api
+ */
+export class ResultSet<
+  T extends ReadonlyArray<ResultSetCell> = ReadonlyArray<ResultSetCell>
+> {
+  constructor(public readonly rows: ReadonlyArray<T>) {}
+}

package/src/api/binary/RQLBinary.ts

@@ -0,0 +1,9 @@
+import { v4 as uuidv4 } from "uuid";
+
+export class RQLBinary {
+  public readonly uuid: string;
+
+  constructor(public readonly blob: Blob) {
+    this.uuid = uuidv4();
+  }
+}

package/src/api/query/RQLQuery.ts

@@ -0,0 +1,51 @@
+import { v4 as uuidv4 } from "uuid";
+import { RQLQueryCellRef, RQLQueryRowRef } from "./references.js";
+import { RQLQueryParams } from "../Api.js";
+
+/**
+ * Class representing a RQL query to be sent to the API.
+ *
+ * Queries are identified by a uuid and are independent from transactions.
+ *
+ * If a query has been used in a transaction, RQLQuery objects can easily retrieve
+ * a reference to the query for later resolving the values in a {@link TransactionResult}.
+ *
+ * @category Api
+ */
+export class RQLQuery {
+  public readonly queryUUID: string;
+
+  /**
+   * Class representing a RQL query to be sent to the API.
+   *
+   * Queries are identified by a uuid and are independent from transactions.
+   *
+   * If a query has been used in a transaction, RQLQuery objects can easily retrieve
+   * a reference to the query for later resolving the values in a {@link TransactionResult}.
+   *
+   * @param rql The rql query
+   * @param params The parameters for the rql query
+   *
+   * @category Api
+   */
+  constructor(
+    public readonly rql: string,
+    public readonly params: RQLQueryParams = {}
+  ) {
+    this.queryUUID = uuidv4();
+  }
+
+  /**
+   * @returns A reference to a {@link ResultSetRow} in the result of this query.
+   */
+  rowRef(row: number): RQLQueryRowRef {
+    return new RQLQueryRowRef(this.queryUUID, row);
+  }
+
+  /**
+   * @returns A reference to a {@link ResultSetCell} in the result of this query.
+   */
+  cellRef(row: number, column: number): RQLQueryCellRef {
+    return new RQLQueryCellRef(this.queryUUID, row, column);
+  }
+}

package/src/api/query/references.ts

@@ -0,0 +1,43 @@
+/**
+ * Class representing a reference to a {@link ResultSetRow} in the result of a {@link RQLQuery}.
+ *
+ * Use this to resolve a {@link ResultSetRow} of the referenced {@link RQLQuery}
+ * from a {@link TransactionResult}.
+ *
+ * @category Api
+ */
+export class RQLQueryRowRef {
+  constructor(public readonly queryUUID: string, public readonly row: number) {}
+
+  /**
+   * Retrieve a reference to the given column in this row.
+   *
+   * @param c The column to get a reference for
+   * @returns A reference to the given column in the current row
+   *
+   * @category Api
+   */
+  column(c: number): RQLQueryCellRef {
+    return new RQLQueryCellRef(this.queryUUID, this.row, c);
+  }
+}
+
+/**
+ * Class representing a reference to a {@link ResultSetCell} in the result of a {@link RQLQuery}.
+ *
+ * Use this to resolve a {@link ResultSetCell} of the referenced {@link RQLQuery}
+ * from a {@link TransactionResult}.
+ *
+ * This reference can also be used in parameters of other {@link RQLQuery}.
+ * If both {@link RQLQuery} are used in the same {@link RQLQuery},
+ * then the resolved value from the first query will be used in the second.
+ *
+ * @category Api
+ */
+export class RQLQueryCellRef {
+  constructor(
+    public readonly queryUUID: string,
+    public readonly row: number,
+    public readonly column: number
+  ) {}
+}

package/src/api/transaction/Transaction.ts

@@ -0,0 +1,31 @@
+import { RQLQuery } from "../query/RQLQuery.js";
+
+/**
+ * Class representing a set of {@link RQLQuery} executed one after the other in a single HTTP request.
+ *
+ * These {@link RQLQuery} can be linked together by using a {@link RQLQueryCellRef}
+ * of one {@link RQLQuery} in the parameters of a subsequent {@link RQLQuery}.
+ *
+ * Binary files are global to the transaction and can be referenced using a {@link RQLQueryBinaryRef}
+ * in the parameters of a {@link RQLQuery}.
+ */
+export class Transaction {
+  private _queries: Array<RQLQuery> = [];
+
+  /**
+   * Adds the given queries to the transaction.
+   *
+   * Each {@link RQLQuery} will be executed one after the other.
+   * These {@link RQLQuery} can be linked together by using a {@link RQLQueryCellRef}
+   * of one {@link RQLQuery} in the parameters of a subsequent {@link RQLQuery}.
+   *
+   * @param queries New queries to add to the transaction
+   */
+  push(...queries: RQLQuery[]): void {
+    this._queries.push(...queries);
+  }
+
+  get queries(): ReadonlyArray<RQLQuery> {
+    return this._queries;
+  }
+}

package/src/api/transaction/TransactionResult.ts

@@ -0,0 +1,46 @@
+import { getQueryIndexInTransaction } from "../../utils.js";
+import { ResultSet, ResultSetCell, ResultSetRow } from "../ResultSet.js";
+import { RQLQuery } from "../query/RQLQuery.js";
+import { RQLQueryCellRef, RQLQueryRowRef } from "../query/references.js";
+import { Transaction } from "./Transaction.js";
+
+/**
+ * Class representing the result of a transaction.
+ *
+ * Retrieving the values is done using query references.
+ *
+ * @example
+ *
+ * Retrieving the first value in a result set
+ *
+ * ```tsx
+ * const transaction = new Transaction()
+ * const query = new RQLQuery("Any X WHERE X name 'test'", {})
+ * transaction.push(query)
+ * const result = client.executeTransaction(transaction)
+ * const eid = result.resolve(query.cellRef(0, 0))
+ * ```
+ *
+ * @category Api
+ */
+export class TransactionResult {
+  constructor(
+    private transaction: Transaction,
+    private resultSets: ReadonlyArray<ResultSet>
+  ) {}
+
+  getResultSet(query: RQLQuery): ResultSet {
+    const index = getQueryIndexInTransaction(this.transaction, query.queryUUID);
+    return this.resultSets[index];
+  }
+
+  getRow(ref: RQLQueryRowRef): ResultSetRow {
+    const index = getQueryIndexInTransaction(this.transaction, ref.queryUUID);
+    return this.resultSets[index].rows[ref.row];
+  }
+
+  getCell(ref: RQLQueryCellRef): ResultSetCell {
+    const index = getQueryIndexInTransaction(this.transaction, ref.queryUUID);
+    return this.resultSets[index].rows[ref.row][ref.column];
+  }
+}

package/src/{Errors.ts → errors.ts}

@@ -1,3 +1,6 @@
+/**
+ * There was an error processing the CubicWeb schema.
+ */
 export class InconsistentSchemaError extends Error {
   constructor(message: string) {
     super(`Inconsistent schema: ${message}`);
@@ -5,16 +8,12 @@ export class InconsistentSchemaError extends Error {
   }
 }
 
+/**
+ * There was an error while validating the data sent to the server.
+ */
 export class ValidationError extends Error {
   constructor(message: string) {
     super(message);
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
-
-export class TransactionClosedError extends Error {
-  constructor() {
-    super("Trying to use a closed transaction");
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}

package/src/index.ts

@@ -11,15 +11,19 @@ export * from "./schema/classes/RelationDefinitionSchema.js";
 export * from "./schema/classes/Schema.js";
 export * from "./schema/classes/Utils.js";
 
-export * from "./Errors.js";
+export * from "./errors.js";
 
 // API
-export { default as Client } from "./api/Client.js";
-export * from "./api/Transaction.js";
 export {
-  RQLQuery,
-  RQLParams,
-  RqlRow,
-  ResultSet,
+  RQLQueryParamValue,
+  RQLQueryParams,
   ApiErrorResponse,
+  CurrentUser,
 } from "./api/Api.js";
+export { ResultSet, ResultSetRow, ResultSetCell } from "./api/ResultSet.js";
+export { default as Client } from "./api/Client.js";
+export { Transaction } from "./api/transaction/Transaction.js";
+export { TransactionResult } from "./api/transaction/TransactionResult.js";
+export { RQLQuery } from "./api/query/RQLQuery.js";
+export { RQLBinary } from "./api/binary/RQLBinary.js";
+export { RQLQueryRowRef, RQLQueryCellRef } from "./api/query/references.js";

package/src/schema/classes/RelationDefinitionSchema.ts

@@ -1,4 +1,4 @@
-import { InconsistentSchemaError } from "../../Errors.js";
+import { InconsistentSchemaError } from "../../errors.js";
 import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   RelationDefinitionRawSchemaArray,

package/src/schema/raw/Constraints.ts

@@ -14,16 +14,25 @@ type ConstraintBase<
  */
 type ConstraintMessage = string | null;
 
+/**
+ * A Unique constraint on an attribute.
+ */
 export type UniqueConstraint = ConstraintBase<
   "UniqueConstraint",
   { msg: ConstraintMessage }
 >;
 
+/**
+ * A constraint on the size of a string
+ */
 export type SizeConstraint = ConstraintBase<
   "SizeConstraint",
   { min: number | null; max: number | null; msg: ConstraintMessage }
 >;
 
+/**
+ * A Regexp constraint on a string
+ */
 export type RegexpConstraint = ConstraintBase<
   "RegexpConstraint",
   { regexp: string; flags: number; msg: ConstraintMessage }
@@ -81,6 +90,9 @@ export interface Now {
  */
 export type ConstraintOperator = ">" | ">=" | "<" | "<=";
 
+/**
+ * A boundary constraint on a number attribute.
+ */
 export type BoundaryConstraint = ConstraintBase<
   "BoundaryConstraint",
   {
@@ -89,6 +101,10 @@ export type BoundaryConstraint = ConstraintBase<
     msg: ConstraintMessage;
   }
 >;
+
+/**
+ * An interval constraint on a number attribute.
+ */
 export type IntervalBoundConstraint = ConstraintBase<
   "IntervalBoundConstraint",
   {
@@ -98,11 +114,17 @@ export type IntervalBoundConstraint = ConstraintBase<
   }
 >;
 
+/**
+ * A static vocabulary constraint on a string attribute.
+ */
 export type StaticVocabularyConstraint = ConstraintBase<
   "StaticVocabularyConstraint",
   { values: string[]; msg: ConstraintMessage }
 >;
 
+/**
+ * A format constraint on a string attribute.
+ */
 export type FormatConstraint = ConstraintBase<
   "FormatConstraint",
   {
@@ -111,11 +133,17 @@ export type FormatConstraint = ConstraintBase<
   }
 >;
 
+/**
+ * A vocabulary constraint on a string attribute described by a RQL.
+ */
 export type RQLVocabularyConstraint = ConstraintBase<
   "RQLVocabularyConstraint",
   { expression: string; mainvars: string[] }
 >;
 
+/**
+ * A constraint on an attribute described by a RQL.
+ */
 export type RQLConstraint = ConstraintBase<
   "RQLConstraint",
   { expression: string; mainvars: string[]; msg: ConstraintMessage }