@cubicweb/client 3.0.0-alpha.10 → 3.0.0-alpha.12

package/src/api/Api.ts

@@ -1,46 +1,35 @@
-import { ValidationError } from "../Errors";
-import { RawSchema } from "../schema/raw/Schema";
-import {
-  TransactionResult,
-  Transaction,
-  TransactionQueryScalarRef,
-  TransactionQueryBinaryRef,
-} from "./Transaction";
+import { ValidationError } from "../errors.js";
+import { RawSchema } from "../schema/raw/Schema.js";
+import { getBinariesFromTransaction, serializeQueryParams } from "../utils.js";
+import { ResultSet } 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,6 +53,9 @@ 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 = {
@@ -74,7 +66,7 @@ export type ApiErrorResponse = {
  * 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 +84,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 +124,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 +170,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 +185,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,18 +208,21 @@ 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>>(
@@ -226,7 +233,7 @@ export default class Api {
         body: formData,
       }
     );
-    return new TransactionResult(resultSets);
+    return new TransactionResult(transaction, resultSets);
   }
 
   private async jsonTransaction(transaction: Transaction) {
@@ -238,7 +245,7 @@ export default class Api {
         body: JSON.stringify(this.getTransactionParams(transaction)),
       }
     );
-    return new TransactionResult(resultSets);
+    return new TransactionResult(transaction, resultSets);
   }
 
   private handleUserErrors(error: unknown): never {

package/src/api/Client.ts

@@ -1,6 +1,9 @@
-import { Schema } from "../schema/classes/Schema";
-import Api, { RQLParams, ResultSet, CurrentUser } from "./Api";
-import { BinariesParam, Transaction, TransactionResult } from "./Transaction";
+import { Schema } from "../schema/classes/Schema.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.
@@ -28,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);
   }
 
   /**
@@ -58,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) {
@@ -84,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
@@ -96,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: 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";
+import { RQLQueryParams } from "../Api";
+
+/**
+ * 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";
+import { ResultSet, ResultSetCell, ResultSetRow } from "../ResultSet";
+import { RQLQuery } from "../query/RQLQuery";
+import { RQLQueryCellRef, RQLQueryRowRef } from "../query/references";
+import { Transaction } from "./Transaction";
+
+/**
+ * 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

@@ -1,25 +1,29 @@
 // Raw Schema
-export * from "./schema/raw/Constraints";
-export * from "./schema/raw/Entities";
-export * from "./schema/raw/RelationDefinitions";
-export * from "./schema/raw/Schema";
-export * from "./schema/raw/Utils";
+export * from "./schema/raw/Constraints.js";
+export * from "./schema/raw/Entities.js";
+export * from "./schema/raw/RelationDefinitions.js";
+export * from "./schema/raw/Schema.js";
+export * from "./schema/raw/Utils.js";
 
 // Schema Abstraction class
-export * from "./schema/classes/EntitySchema";
-export * from "./schema/classes/RelationDefinitionSchema";
-export * from "./schema/classes/Schema";
-export * from "./schema/classes/Utils";
+export * from "./schema/classes/EntitySchema.js";
+export * from "./schema/classes/RelationDefinitionSchema.js";
+export * from "./schema/classes/Schema.js";
+export * from "./schema/classes/Utils.js";
 
-export * from "./Errors";
+export * from "./errors.js";
 
 // API
-export { default as Client } from "./api/Client";
-export * from "./api/Transaction";
 export {
-  RQLQuery,
-  RQLParams,
-  RqlRow,
-  ResultSet,
+  RQLQueryParamValue,
+  RQLQueryParams,
   ApiErrorResponse,
-} from "./api/Api";
+  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/EntitySchema.ts

@@ -1,8 +1,11 @@
-import { EntityRawSchemaArray } from "../raw/Entities";
-import { RelationDefinitionRawSchemaArray } from "../raw/RelationDefinitions";
-import { RelationDefinitionSchema } from "./RelationDefinitionSchema";
-import { Schema } from "./Schema";
-import { MatchedRelationDefinition, RelationDefinitionMatcher } from "./Utils";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
+import { RelationDefinitionRawSchemaArray } from "../raw/RelationDefinitions.js";
+import { RelationDefinitionSchema } from "./RelationDefinitionSchema.js";
+import { Schema } from "./Schema.js";
+import {
+  MatchedRelationDefinition,
+  RelationDefinitionMatcher,
+} from "./Utils.js";
 
 /**
  * Wrapper around raw entity schemas from the Schema.

package/src/schema/classes/RelationDefinitionSchema.ts

@@ -1,13 +1,13 @@
-import { InconsistentSchemaError } from "../../Errors";
-import { EntityRawSchemaArray } from "../raw/Entities";
+import { InconsistentSchemaError } from "../../errors.js";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   RelationDefinitionRawSchemaArray,
   Cardinality,
-} from "../raw/RelationDefinitions";
-import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils";
-import { EntitySchema } from "./EntitySchema";
-import { Schema } from "./Schema";
-import { EntityRole, isCardinalityRequired } from "./Utils";
+} from "../raw/RelationDefinitions.js";
+import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils.js";
+import { EntitySchema } from "./EntitySchema.js";
+import { Schema } from "./Schema.js";
+import { EntityRole, isCardinalityRequired } from "./Utils.js";
 
 /**
  * Wrapper around raw relation definition schemas from the Schema.

package/src/schema/classes/Schema.ts

@@ -1,17 +1,20 @@
-import { EntityRawSchemaArray } from "../raw/Entities";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   RelationDefinitionRawSchema,
   RelationDefinitionRawSchemaArray,
-} from "../raw/RelationDefinitions";
-import { RawSchema } from "../raw/Schema";
+} from "../raw/RelationDefinitions.js";
+import { RawSchema } from "../raw/Schema.js";
 import {
   EntityRawSchemaByType,
   IsETypeInStrictSchema,
   IsLooseSchema,
-} from "../raw/Utils";
-import { EntitySchema } from "./EntitySchema";
-import { RelationDefinitionSchema } from "./RelationDefinitionSchema";
-import { RelationDefinitionMatcher, MatchedRelationDefinition } from "./Utils";
+} from "../raw/Utils.js";
+import { EntitySchema } from "./EntitySchema.js";
+import { RelationDefinitionSchema } from "./RelationDefinitionSchema.js";
+import {
+  RelationDefinitionMatcher,
+  MatchedRelationDefinition,
+} from "./Utils.js";
 
 const rawSchemaKey: unique symbol = Symbol("Indexer of the rawSchema");
 

package/src/schema/classes/Utils.ts

@@ -1,11 +1,11 @@
-import { EntityRawSchemaArray } from "../raw/Entities";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   Cardinality,
   RelationDefinitionRawSchema,
   RelationDefinitionRawSchemaArray,
-} from "../raw/RelationDefinitions";
-import { Schema } from "./Schema";
-import { EntitySchema } from "./EntitySchema";
+} from "../raw/RelationDefinitions.js";
+import { Schema } from "./Schema.js";
+import { EntitySchema } from "./EntitySchema.js";
 
 // This prefix is often applied to relation types as convention
 // indicating a relation is viewed from the object's point of view