@cubicweb/client 3.0.0-alpha.4 → 3.0.0-alpha.5

package/src/api/Api.ts

@@ -8,12 +8,16 @@ import {
 
 /**
  * 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;
@@ -21,16 +25,22 @@ export interface RQLParams {
 
 /**
  * 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 +50,8 @@ export interface CurrentUser {
 
 /**
  * Type representing the body of an error sent by CubicWeb's API.
+ *
+ * @category Api
  */
 type ApiError = {
   title: string;
@@ -49,6 +61,8 @@ type ApiError = {
 
 /**
  * Type representing the error data sent to clients when retrieving an API error.
+ *
+ * @category Api
  */
 export type ApiErrorResponse = {
   status: number;
@@ -69,7 +83,7 @@ export default class Api {
   private _schemaApiUrl: string;
   private _loginApiUrl: string;
   private _currentUserApiUrl: string;
-  private _transactionApiUrl: string;
+  private _binaryApiUrl: string;
 
   /**
    * Class used to handle requests to the CubicWeb API.
@@ -87,7 +101,7 @@ export default class Api {
     this._schemaApiUrl = this.getApiRoute("schema");
     this._loginApiUrl = this.getApiRoute("login");
     this._currentUserApiUrl = this.getApiRoute("current-user");
-    this._transactionApiUrl = this.getApiRoute("transaction");
+    this._binaryApiUrl = this.getApiRoute("binary");
   }
 
   get apiUrl() {
@@ -98,25 +112,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.
    *
@@ -164,10 +159,36 @@ 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]) => [
@@ -182,19 +203,37 @@ export default class Api {
         ])
       ),
     }));
-    try {
-      const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
-        this._transactionApiUrl,
-        {
-          method: "POST",
-          credentials: "include",
-          body: JSON.stringify(data),
-        }
-      );
-      return new TransactionResult(resultSets);
-    } catch (e) {
-      this.handleUserErrors(e);
-    }
+  }
+
+  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._rqlApiUrl,
+      {
+        method: "POST",
+        credentials: "include",
+        body: JSON.stringify(this.getTransactionParams(transaction)),
+      }
+    );
+    return new TransactionResult(resultSets);
   }
 
   private handleUserErrors(error: unknown): never {
@@ -257,6 +296,8 @@ async function fetchApi<R = unknown>(
   if (init?.method && init.method !== "GET" && init.method !== "DELETE") {
     headers = {
       "Content-Type": "application/json;charset=UTF-8",
+      // CSRF custom header necessary for POST requests
+      "X-Requested-With": "XMLHttpRequest",
       ...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();
+    transaction.push(query, params);
+    transaction.setBinaries(binaries);
+    const result = await this.executeTransaction(transaction);
+    return result.get(0);
   }
 
   /**
@@ -86,6 +81,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,7 +1,10 @@
-import Api, { ResultSet, RQLParamValue } from "./Api";
+import { ResultSet, RQLParamValue } from "./Api";
+
+export type BinariesParam = Record<string, Blob>;
 
 export class Transaction {
   private _queries: Array<TransactionQuery> = [];
+  private _binaries: BinariesParam = {};
 
   push(
     query: string,
@@ -16,6 +19,14 @@ export class Transaction {
     return stackedQuery;
   }
 
+  setBinaries(binaries?: BinariesParam) {
+    this._binaries = binaries ?? {};
+  }
+
+  get binaries(): BinariesParam {
+    return this._binaries;
+  }
+
   get queries(): ReadonlyArray<TransactionQuery> {
     return this._queries;
   }
@@ -24,6 +35,10 @@ export class Transaction {
 export class TransactionResult {
   constructor(private resultSets: ReadonlyArray<ResultSet>) {}
 
+  get(queryIndex: number): ResultSet {
+    return this.resultSets[queryIndex];
+  }
+
   resolve(ref: TransactionQueryRef) {
     return this.resultSets[ref.queryIndex][ref.row][ref.column];
   }
@@ -62,14 +77,3 @@ export function isTransactionQueryRef(
     )
   );
 }
-
-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);
-  }
-}

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,

package/src/schema/classes/RelationDefinitionSchema.ts

@@ -13,6 +13,8 @@ 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,

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,

package/src/schema/classes/Utils.ts

@@ -14,6 +14,8 @@ const REVERSE_INDICATOR = "reverse_";
 
 /**
  * An entity role in a relation.
+ *
+ * @category Utils
  */
 export type EntityRole = "subject" | "object";
 
@@ -23,6 +25,8 @@ export type EntityRole = "subject" | "object";
  *
  * @param schema The schema to create a loose type for
  * @returns A loosely typed schema
+ *
+ * @category Utils
  */
 export const getLooseSchema = <
   E extends EntityRawSchemaArray = EntityRawSchemaArray,
@@ -38,6 +42,8 @@ export const getLooseSchema = <
  *
  * @param cardinality The cardinality to check
  * @returns True if the cardinality is 1 or +
+ *
+ * @category Utils
  */
 export function isCardinalityRequired(cardinality: Cardinality): boolean {
   return cardinality === "1" || cardinality === "+";
@@ -48,6 +54,8 @@ export function isCardinalityRequired(cardinality: Cardinality): boolean {
  *
  * @param cardinality The cardinility to check
  * @returns True if the cardinality is `*` or `+`
+ *
+ * @category Utils
  */
 export const isCardinalityMultiple = (cardinality: Cardinality): boolean => {
   return cardinality === "*" || cardinality === "+";
@@ -58,6 +66,8 @@ export const isCardinalityMultiple = (cardinality: Cardinality): boolean => {
  *
  * @param cardinality The cardinility to check
  * @returns True if the cardinality is `?` or `*`
+ *
+ * @category Utils
  */
 export const isCardinalityOptional = (cardinality: Cardinality): boolean => {
   return cardinality === "?" || cardinality === "*";
@@ -68,6 +78,8 @@ export const isCardinalityOptional = (cardinality: Cardinality): boolean => {
  *
  * @param role The role to reverse
  * @returns "object" if the given role was "subject", "subject" otherwise
+ *
+ * @category Utils
  */
 export function getOppositeRelationRole(role: EntityRole): EntityRole {
   return role === "subject" ? "object" : "subject";
@@ -82,6 +94,8 @@ export function getOppositeRelationRole(role: EntityRole): EntityRole {
  *
  * @param relationType The relation type to check
  * @returns True if the relation type starts with the reverse indicator
+ *
+ * @category Utils
  */
 export const isRelationTypeReversed = (relationType: string): boolean => {
   return relationType.startsWith(REVERSE_INDICATOR);
@@ -97,6 +111,8 @@ export const isRelationTypeReversed = (relationType: string): boolean => {
  *
  * @param relationType The relation type to check
  * @returns "subject" if the relation is not reversed, "object" otherwise
+ *
+ * @category Utils
  */
 export const getRoleFromRelationType = (relationType: string): EntityRole => {
   return isRelationTypeReversed(relationType) ? "object" : "subject";
@@ -111,6 +127,8 @@ export const getRoleFromRelationType = (relationType: string): EntityRole => {
  *
  * @param relationType The relation type to transform
  * @returns The relation type with the reverse indicator added or removed
+ *
+ * @category Utils
  */
 export const getReverseRelationType = (relationType: string): string => {
   if (!isRelationTypeReversed(relationType)) {
@@ -129,6 +147,8 @@ export const getReverseRelationType = (relationType: string): string => {
  *
  * @param relationType The relation type to transform
  * @returns The relation type with the reverse indicator added or removed
+ *
+ * @category Utils
  */
 export const getRawRelationType = (relationType: string): string => {
   if (isRelationTypeReversed(relationType)) {
@@ -148,6 +168,8 @@ export const getRawRelationType = (relationType: string): string => {
  * @param relationType The relation type to transform
  * @param role The entity role in the relation
  * @returns A relation type with the reverse indicator if necessary
+ *
+ * @category Utils
  */
 export const getRelationType = (relationType: string, role: EntityRole) => {
   return role === "subject"
@@ -163,6 +185,8 @@ export const getRelationType = (relationType: string, role: EntityRole) => {
  * @param relationType The type of the relation to use. Can have the reverse indicator to decide the role of the source/target entities
  * @param targetType The entity type acting as target for the relation
  * @returns The relation definition matching the triplet source relation target
+ *
+ * @category Utils
  */
 export const getRelationDefinition = (
   entitySchema: EntitySchema,
@@ -184,6 +208,8 @@ export const getRelationDefinition = (
 
 /**
  * Partial raw relation definition schema type.
+ *
+ * @category Utils
  */
 export type RelationDefinitionMatcher<E extends EntityRawSchemaArray> = Partial<
   RelationDefinitionRawSchema<E>
@@ -194,6 +220,8 @@ export type RelationDefinitionMatcher<E extends EntityRawSchemaArray> = Partial<
  * If it finds a relation definition matching the partial one given, it will return its type.
  * If it cannot find any relation definition matching, it will return the `never` type
  * and TypeScript will give compile errors.
+ *
+ * @category Utils
  */
 export type MatchedRelationDefinition<
   E extends EntityRawSchemaArray,

package/src/schema/raw/Constraints.ts

@@ -10,7 +10,7 @@ type ConstraintBase<
 };
 
 /**
- * THe type of a constraint message when one is present.
+ * The type of a constraint message when one is present.
  */
 type ConstraintMessage = string | null;
 
@@ -33,6 +33,8 @@ export type RegexpConstraint = ConstraintBase<
  * Reference to an attribute used in constraints.
  *
  * @property \_\_attribute\_\_ name of the attribute in the same entity
+ *
+ * @category Schema
  */
 export interface Attribute {
   __attribute__: string;
@@ -50,6 +52,8 @@ export interface TimeDelta {
  * @property \_\_today\_\_ always true
  * @property offset delta to current date at the time of the check
  * @property type name of the Python class used to do the comparison
+ *
+ * @category Schema
  */
 export interface Today {
   __today__: true;
@@ -62,6 +66,8 @@ export interface Today {
  *
  * @property \_\_now\_\_ always true
  * @property offset delta to current date at the time of the check
+ *
+ * @category Schema
  */
 export interface Now {
   __now__: true;
@@ -70,13 +76,11 @@ export interface Now {
 
 /**
  * All the possible operators inside a constraint.
+ *
+ * @category Schema
  */
 export type ConstraintOperator = ">" | ">=" | "<" | "<=";
 
-/**
- * @property value.boundary boudary value to compare the attribut
- *
- */
 export type BoundaryConstraint = ConstraintBase<
   "BoundaryConstraint",
   {
@@ -115,6 +119,8 @@ export type RQLConstraint = ConstraintBase<
 
 /**
  * Type representing all possible constraints for attributes.
+ *
+ * @category Schema
  */
 export type AttributeConstraint = Readonly<
   | UniqueConstraint
@@ -129,6 +135,8 @@ export type AttributeConstraint = Readonly<
 
 /**
  * Type representing all possible constraints for relations.
+ *
+ * @category Schema
  */
 export type RelationConstraint = Readonly<
   RQLVocabularyConstraint | RQLConstraint

package/src/schema/raw/Entities.ts

@@ -1,5 +1,7 @@
 /**
  * Type representing an entity schema.
+ *
+ * @category Schema
  */
 export type EntityRawSchema = {
   type: string;
@@ -9,5 +11,7 @@ export type EntityRawSchema = {
 
 /**
  * Type representing a list of entity schemas.
+ *
+ * @category Schema
  */
 export type EntityRawSchemaArray = ReadonlyArray<EntityRawSchema>;

package/src/schema/raw/RelationDefinitions.ts

@@ -4,11 +4,15 @@ import { EntityRawSchema, EntityRawSchemaArray } from "./Entities";
 
 /**
  * Type representing all the possible cardinalities in CubicWeb.
+ *
+ * @category Schema
  */
 export type Cardinality = "*" | "1" | "?" | "+";
 
 /**
  * Type representing a cardinality pair as used in relation definitions.
+ *
+ * @category Schema
  */
 export type CardinalityPair = `${Cardinality}${Cardinality}`;
 
@@ -110,6 +114,8 @@ export type BuildObj = Readonly<
 
 /**
  * Type representing the possible options for an attribute.
+ *
+ * @category Schema
  */
 export type AttributeOptions = {
   indexed?: boolean;
@@ -119,6 +125,8 @@ export type AttributeOptions = {
 
 /**
  * Type representing the possible options for a relation definition.
+ *
+ * @category Schema
  */
 export type RelationOptions = {
   symmetric?: boolean;
@@ -132,6 +140,8 @@ export type RelationOptions = {
  * It can represent both attributes and relations depending on the value of Final.
  *
  * It can infer default values type depending on the object type if the relation is final.
+ *
+ * @category Schema
  */
 export type RelationDefinitionRawSchema<
   ESchemas extends EntityRawSchemaArray,
@@ -158,6 +168,8 @@ export type RelationDefinitionRawSchema<
 
 /**
  * Type representing a list of relation definitions.
+ *
+ * @category Schema
  */
 export type RelationDefinitionRawSchemaArray<
   ESchemas extends EntityRawSchemaArray

package/src/schema/raw/Schema.ts

@@ -6,6 +6,8 @@ import { RelationDefinitionRawSchemaArray } from "./RelationDefinitions";
  * You can export this schema from your CubicWeb instance using the command:
  *
  * `cubicweb-ctl export-schema -f typescript <YOUR_INSTANCE_NAME>`
+ *
+ * @category Schema
  */
 export type RawSchema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,

package/src/schema/raw/Utils.ts

@@ -6,6 +6,8 @@ import { EntityRawSchemaArray } from "./Entities";
  *
  * In the given EntityRawSchemaArray, if the entities type is a string, the schema is loosely typed.
  * If the schema is strongly typed, the entities type would be a word (which is stricter than string).
+ *
+ * @category Schema
  */
 export type IsLooseSchema<E extends EntityRawSchemaArray> =
   string extends E[number]["type"] ? true : false;
@@ -13,6 +15,8 @@ export type IsLooseSchema<E extends EntityRawSchemaArray> =
 /**
  * Checks if the given entity type is present in the EntityRawSchemaArray.
  * Use this to create conditional types.
+ *
+ * @category Schema
  */
 export type IsETypeInStrictSchema<
   E extends EntityRawSchemaArray,
@@ -22,6 +26,8 @@ export type IsETypeInStrictSchema<
 /**
  * Type representing the entity's raw schema matching this type.
  * This type only works for EntityRawSchemaArray with literals as "type" property.
+ *
+ * @category Schema
  */
 export type EntityRawSchemaByType<
   E extends EntityRawSchemaArray,