@cubicweb/client 2.1.0 → 3.0.0-alpha.10

package/src/api/Api.ts

@@ -3,34 +3,46 @@ import { RawSchema } from "../schema/raw/Schema";
 import {
   TransactionResult,
   Transaction,
-  isTransactionQueryRef,
+  TransactionQueryScalarRef,
+  TransactionQueryBinaryRef,
 } from "./Transaction";
 
 /**
  * Type representing an RQL request and its associated parameters.
+ *
+ * @category Api
  */
 export type RQLQuery = [string, RQLParams];
 
 export type RQLParamValue = string | number | boolean | null;
 /**
  * Type representing RQL parameters to send along a request.
+ *
+ * @category Api
  */
-export interface RQLParams {
-  [key: string]: RQLParamValue;
-}
+export type RQLParams = Record<
+  string,
+  RQLParamValue | TransactionQueryScalarRef | TransactionQueryBinaryRef
+>;
 
 /**
  * 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
+ *
+ * @category Api
  */
 export interface CurrentUser {
   login: string;
@@ -40,6 +52,8 @@ export interface CurrentUser {
 
 /**
  * Type representing the body of an error sent by CubicWeb's API.
+ *
+ * @category Api
  */
 type ApiError = {
   title: string;
@@ -49,6 +63,8 @@ type ApiError = {
 
 /**
  * Type representing the error data sent to clients when retrieving an API error.
+ *
+ * @category Api
  */
 export type ApiErrorResponse = {
   status: number;
@@ -68,8 +84,9 @@ export default class Api {
   private _rqlApiUrl: string;
   private _schemaApiUrl: string;
   private _loginApiUrl: string;
+  private _logoutApiUrl: string;
   private _currentUserApiUrl: string;
-  private _transactionApiUrl: string;
+  private _binaryApiUrl: string;
 
   /**
    * Class used to handle requests to the CubicWeb API.
@@ -86,8 +103,9 @@ export default class Api {
     this._rqlApiUrl = this.getApiRoute("rql");
     this._schemaApiUrl = this.getApiRoute("schema");
     this._loginApiUrl = this.getApiRoute("login");
+    this._logoutApiUrl = this.getApiRoute("logout");
     this._currentUserApiUrl = this.getApiRoute("current-user");
-    this._transactionApiUrl = this.getApiRoute("transaction");
+    this._binaryApiUrl = this.getApiRoute("binary");
   }
 
   get apiUrl() {
@@ -98,25 +116,6 @@ export default class Api {
     return `${this._apiUrl}/${this._version}/${route}`;
   }
 
-  /**
-   * Executes the given query and waits for the response.
-   *
-   * @param query 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): Promise<ResultSet> {
-    try {
-      return await nonNullFetchApi<ResultSet>(this._rqlApiUrl, {
-        method: "POST",
-        body: JSON.stringify({ query, params }),
-        credentials: "include", // FIXME is it secure?
-      });
-    } catch (e) {
-      this.handleUserErrors(e);
-    }
-  }
-
   /**
    * Retrieves the CubicWeb instance's JSON schema.
    *
@@ -152,6 +151,18 @@ export default class Api {
     }
   }
 
+  /**
+   * Logs out the current user. Will invalidate any authentication cookie active.
+   *
+   * @returns A promise which will resolve when the user is properly logged out
+   */
+  async logout(): Promise<void> {
+    await fetchApi<null>(this._logoutApiUrl, {
+      method: "POST",
+      credentials: "include",
+    });
+  }
+
   /**
    * Get the current user associated to this client
    *
@@ -164,30 +175,67 @@ export default class Api {
     });
   }
 
-  async executeTransaction(
-    transaction: Transaction
-  ): Promise<TransactionResult> {
-    const data = transaction.queries.map((transactionQuery) => ({
+  /**
+   * Get the binary for the given entity attribute
+   *
+   * @returns A promise resolving to the binary
+   */
+  async binary(eid: number, attribute: string): Promise<Blob> {
+    const params = new URLSearchParams({
+      eid: eid.toString(),
+      attribute,
+    });
+    return await nonNullFetchApi<Blob>(this._binaryApiUrl + params, {
+      method: "GET",
+      credentials: "include",
+    });
+  }
+
+  async rql(transaction: Transaction): Promise<TransactionResult> {
+    try {
+      if (Object.keys(transaction.binaries).length > 0) {
+        return await this.multipartTransaction(transaction);
+      } else {
+        return await this.jsonTransaction(transaction);
+      }
+    } catch (e) {
+      this.handleUserErrors(e);
+    }
+  }
+
+  private getTransactionParams(transaction: Transaction) {
+    return transaction.queries.map((transactionQuery) => ({
       query: transactionQuery.query,
-      params: Object.fromEntries(
-        Object.entries(transactionQuery.params).map(([key, value]) => [
-          key,
-          isTransactionQueryRef(value)
-            ? {
-                queryIndex: value.queryIndex,
-                row: value.row,
-                column: value.column,
-              }
-            : value,
-        ])
-      ),
+      params: transactionQuery.params,
     }));
+  }
+
+  private async multipartTransaction(transaction: Transaction) {
+    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);
+    });
+
+    const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
+      this._rqlApiUrl,
+      {
+        method: "POST",
+        credentials: "include",
+        body: formData,
+      }
+    );
+    return new TransactionResult(resultSets);
+  }
+
+  private async jsonTransaction(transaction: Transaction) {
     const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
-      this._transactionApiUrl,
+      this._rqlApiUrl,
       {
         method: "POST",
         credentials: "include",
-        body: JSON.stringify(data),
+        body: JSON.stringify(this.getTransactionParams(transaction)),
       }
     );
     return new TransactionResult(resultSets);
@@ -250,9 +298,18 @@ async function fetchApi<R = unknown>(
   init?: RequestInit
 ): Promise<R | null> {
   let headers = init?.headers;
-  if (init?.method && init.method !== "GET" && init.method !== "DELETE") {
+  if (init?.method && init.method !== "GET") {
+    headers = {
+      // CSRF custom header necessary for POST requests
+      "X-Client-Name": "XMLHttpRequest",
+    };
+    // Browsers will automatically set the multipart content type
+    // with the right boundary if the body is FormData
+    if (!(init.body instanceof FormData)) {
+      headers["Content-Type"] = "application/json;charset=UTF-8";
+    }
     headers = {
-      "Content-Type": "application/json;charset=UTF-8",
+      ...headers,
       ...init?.headers,
     };
   }

package/src/api/Client.ts

@@ -1,18 +1,14 @@
 import { Schema } from "../schema/classes/Schema";
 import Api, { RQLParams, ResultSet, CurrentUser } from "./Api";
-import {
-  NativeTransactionBackend,
-  Transaction,
-  TransactionBackend,
-  TransactionResult,
-} from "./Transaction";
+import { BinariesParam, Transaction, TransactionResult } from "./Transaction";
 
 /**
  * Class used to communicate with a CubicWeb instance's API.
+ *
+ * @category Api
  */
 export default class Client {
   private api: Api;
-  private transactionBackend: TransactionBackend;
 
   /**
    * Class used to communicate with a CubicWeb instance's API.
@@ -21,17 +17,8 @@ export default class Client {
    * Example: if you can retrieve the schema with https://example.com/api/v1/schema,
    * use https://example.com/api as `apiUrl`.
    */
-  constructor(
-    apiUrl: string,
-    options: { transactionBackend?: TransactionBackend } = {}
-  ) {
+  constructor(apiUrl: string) {
     this.api = new Api(apiUrl);
-    const { transactionBackend } = options;
-    if (transactionBackend === undefined) {
-      this.transactionBackend = new NativeTransactionBackend(this.api);
-    } else {
-      this.transactionBackend = transactionBackend;
-    }
   }
 
   get apiUrl() {
@@ -45,8 +32,16 @@ export default class Client {
    * @param params The additional parameters for the request
    * @returns A promise with the request's result set
    */
-  async execute(query: string, params: RQLParams = {}): Promise<ResultSet> {
-    return await this.api.execute(query, params);
+  async execute(
+    query: string,
+    params: RQLParams = {},
+    binaries?: BinariesParam
+  ): Promise<ResultSet> {
+    const transaction = new Transaction();
+    const transactionQuery = transaction.push(query, params);
+    transaction.setBinaries(binaries);
+    const result = await this.executeTransaction(transaction);
+    return result.resolveQuery(transactionQuery.ref());
   }
 
   /**
@@ -70,6 +65,15 @@ export default class Client {
     return await this.api.login(login, password);
   }
 
+  /**
+   * Logs out the current user. Will invalidate any authentication cookie active.
+   *
+   * @returns A promise which will resolve when the user is properly logged out
+   */
+  async logout() {
+    return await this.api.logout();
+  }
+
   /**
    * Get the user associated to this client
    *
@@ -86,6 +90,15 @@ export default class Client {
   async executeTransaction(
     transaction: Transaction
   ): Promise<TransactionResult> {
-    return await this.transactionBackend.execute(transaction);
+    return await this.api.rql(transaction);
+  }
+
+  /**
+   * Get the binary for the given entity attribute
+   *
+   * @returns A promise resolving to the binary
+   */
+  async getBinary(eid: number, attribute: string) {
+    return await this.api.binary(eid, attribute);
   }
 }

package/src/api/Transaction.ts

@@ -1,12 +1,12 @@
-import Api, { ResultSet, RQLParamValue } from "./Api";
+import { RQLParams, ResultSet } from "./Api";
+
+export type BinariesParam = Record<string, Blob>;
 
 export class Transaction {
   private _queries: Array<TransactionQuery> = [];
+  private _binaries: BinariesParam = {};
 
-  push(
-    query: string,
-    params: Record<string, RQLParamValue | TransactionQueryRef>
-  ): TransactionQuery {
+  push(query: string, params: RQLParams): TransactionQuery {
     const stackedQuery = new TransactionQuery(
       query,
       params,
@@ -16,60 +16,79 @@ export class Transaction {
     return stackedQuery;
   }
 
+  setBinaries(binaries?: BinariesParam) {
+    this._binaries = binaries ?? {};
+  }
+
+  get binaries(): BinariesParam {
+    return this._binaries;
+  }
+
   get queries(): ReadonlyArray<TransactionQuery> {
     return this._queries;
   }
 }
 
+export class TransactionQuery {
+  constructor(
+    public readonly query: string,
+    public readonly params: RQLParams,
+    public readonly index: number
+  ) {}
+
+  ref(): TransactionQueryRef {
+    return new TransactionQueryRef(this.index);
+  }
+}
+
 export class TransactionResult {
   constructor(private resultSets: ReadonlyArray<ResultSet>) {}
 
-  resolve(ref: TransactionQueryRef) {
+  resolveQuery(ref: TransactionQueryRef) {
+    return this.resultSets[ref.queryIndex];
+  }
+
+  resolveRow(ref: TransactionQueryRowRef) {
+    return this.resultSets[ref.queryIndex][ref.row];
+  }
+
+  resolveScalar(ref: TransactionQueryScalarRef) {
     return this.resultSets[ref.queryIndex][ref.row][ref.column];
   }
 }
 
-export interface TransactionQueryRef {
-  queryIndex: number;
-  row: number;
-  column: number;
+export class TransactionQueryRef {
+  constructor(public readonly queryIndex: number) {}
+
+  row(r: number): TransactionQueryRowRef {
+    return new TransactionQueryRowRef(this.queryIndex, r);
+  }
 }
 
-export class TransactionQuery {
+export class TransactionQueryRowRef {
   constructor(
-    public readonly query: string,
-    public readonly params: Record<string, RQLParamValue | TransactionQueryRef>,
-    public readonly index: number
+    public readonly queryIndex: number,
+    public readonly row: number
   ) {}
 
-  ref(row = 0, column = 0): TransactionQueryRef {
+  column(c: number): TransactionQueryScalarRef {
     return {
-      queryIndex: this.index,
-      row,
-      column,
+      type: "query_reference",
+      queryIndex: this.queryIndex,
+      row: this.row,
+      column: c,
     };
   }
 }
 
-export function isTransactionQueryRef(
-  value: RQLParamValue | TransactionQueryRef
-): value is TransactionQueryRef {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    ["queryIndex", "row", "column"].every((key) =>
-      Object.keys(value).includes(key)
-    )
-  );
+export interface TransactionQueryScalarRef {
+  readonly queryIndex: number;
+  readonly row: number;
+  readonly column: number;
+  readonly type: "query_reference";
 }
 
-export interface TransactionBackend {
-  execute(transaction: Transaction): Promise<TransactionResult>;
-}
-
-export class NativeTransactionBackend implements TransactionBackend {
-  constructor(private _api: Api) {}
-  async execute(transaction: Transaction): Promise<TransactionResult> {
-    return this._api.executeTransaction(transaction);
-  }
+export interface TransactionQueryBinaryRef {
+  readonly ref: string;
+  readonly type: "binary_reference";
 }

package/src/schema/classes/EntitySchema.ts

@@ -8,6 +8,8 @@ import { MatchedRelationDefinition, RelationDefinitionMatcher } from "./Utils";
  * Wrapper around raw entity schemas from the Schema.
  * You should never have to create this object yourself.
  * Instead, retrieve these objects from the methods in the `Schema` class.
+ *
+ * @category Schema
  */
 export class EntitySchema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,
@@ -49,43 +51,54 @@ export class EntitySchema<
   }
 
   /**
-   * Gets the list of relation definitions schemas with this entity as subject.
-   * In case a relation definition schema has this entity as both object and subject,
-   * there will be dupicates when used along with `objectRelationsDefinitions`.
+   * Gets the list of attribute schemas (relation definition schemas with final at false)
+   * for this entity schema.
    */
-  get subjectRelationDefinitions(): RelationDefinitionSchema<
+  get attributes(): RelationDefinitionSchema<
     E,
     R,
     MatchedRelationDefinition<
       E,
       R,
-      { subject: ERawSchema["type"]; final: false }
+      { subject: ERawSchema["type"]; final: true }
     >
   >[] {
     return this.schema.matchRelationDefinitions({
+      final: true,
       subject: this.type,
-      final: false,
     });
   }
 
-  /**
-   * Gets the list of relation definitions schemas with this entity as object.
-   * In case a relation definition schema has this entity as both object and subject,
-   * there will be dupicates when used along with `subjectRelationDefinitions`.
-   */
-  get objectRelationsDefinitions(): RelationDefinitionSchema<
-    E,
-    R,
-    MatchedRelationDefinition<
+  get relationDefinitions(): {
+    subject: RelationDefinitionSchema<
       E,
       R,
-      { object: ERawSchema["type"]; final: false }
-    >
-  >[] {
-    return this.schema.matchRelationDefinitions({
-      object: this.type,
-      final: false,
-    });
+      MatchedRelationDefinition<
+        E,
+        R,
+        { subject: ERawSchema["type"]; final: false }
+      >
+    >[];
+    object: RelationDefinitionSchema<
+      E,
+      R,
+      MatchedRelationDefinition<
+        E,
+        R,
+        { object: ERawSchema["type"]; final: false }
+      >
+    >[];
+  } {
+    return {
+      subject: this.schema.matchRelationDefinitions({
+        subject: this.type,
+        final: false,
+      }),
+      object: this.schema.matchRelationDefinitions({
+        object: this.type,
+        final: false,
+      }),
+    };
   }
 
   /**
@@ -103,23 +116,4 @@ export class EntitySchema<
   >[] {
     return this.schema.matchRelationDefinitions(matcher);
   }
-
-  /**
-   * Gets the list of attribute schemas (relation definition schemas with final at false)
-   * for this entity schema.
-   */
-  get attributes(): RelationDefinitionSchema<
-    E,
-    R,
-    MatchedRelationDefinition<
-      E,
-      R,
-      { subject: ERawSchema["type"]; final: true }
-    >
-  >[] {
-    return this.schema.matchRelationDefinitions({
-      final: true,
-      subject: this.type,
-    });
-  }
 }

package/src/schema/classes/RelationDefinitionSchema.ts

@@ -7,12 +7,14 @@ import {
 import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils";
 import { EntitySchema } from "./EntitySchema";
 import { Schema } from "./Schema";
-import { cardinalityRequired } from "./Utils";
+import { EntityRole, isCardinalityRequired } from "./Utils";
 
 /**
  * Wrapper around raw relation definition schemas from the Schema.
  * You should never have to create this object yourself.
  * Instead, retrieve these objects from the methods in the `Schema` class.
+ *
+ * @category Schema
  */
 export class RelationDefinitionSchema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,
@@ -84,22 +86,11 @@ export class RelationDefinitionSchema<
   /**
    * The cardinality of this relation definition schema.
    */
-  get cardinality(): RDef["cardinality"] {
-    return this.relDef.cardinality;
-  }
-
-  /**
-   * The cardinality of this relation definition schema's subject.
-   */
-  get subjectCardinality(): Cardinality {
-    return this.relDef.cardinality[0] as Cardinality;
-  }
-
-  /**
-   * The cardinality of this relation definition schema's object.
-   */
-  get objectCardinality(): Cardinality {
-    return this.relDef.cardinality[1] as Cardinality;
+  get cardinality(): { subject: Cardinality; object: Cardinality } {
+    return {
+      subject: this.relDef.cardinality[0] as Cardinality,
+      object: this.relDef.cardinality[1] as Cardinality,
+    };
   }
 
   /**
@@ -144,13 +135,7 @@ export class RelationDefinitionSchema<
    * @param role The point of view to use
    * @returns
    */
-  isRequired(role: "subject" | "object") {
-    let cardinality: Cardinality;
-    if (role === "subject") {
-      cardinality = this.subjectCardinality;
-    } else {
-      cardinality = this.objectCardinality;
-    }
-    return cardinalityRequired(cardinality);
+  isRequired(role: EntityRole) {
+    return isCardinalityRequired(this.cardinality[role]);
   }
 }

package/src/schema/classes/Schema.ts

@@ -19,6 +19,8 @@ const rawSchemaKey: unique symbol = Symbol("Indexer of the rawSchema");
  * Wrapper around the raw JSON Schema.
  * It is recommended to use this class instead of the raw JSON Schema
  * as it is more robust to schema changes and provides utility functions.
+ *
+ * @category Schema
  */
 export class Schema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,