@cubicweb/client 1.5.0 → 1.6.0

package/README.md

@@ -0,0 +1,207 @@
+# @cubicweb/client
+
+This library is the [CubicWeb](https://cubicweb.org/) JavaScript client
+used to communicate with instances running with the
+[API cube](https://forge.extranet.logilab.fr/cubicweb/cubes/api).
+It replaces the [cwclientlibjs](https://forge.extranet.logilab.fr/open-source/cwclientlibjs)
+library.
+
+The full documentation is available [here](https://cubicweb.pages.logilab.fr/cubicwebjs/client).
+
+## Installation
+
+@cubicweb/client is avalaible from NPM:
+```bash
+# With NPM
+npm i @cubicweb/client
+# Or with Yarn
+yarn add @cubicweb/client
+```
+
+Then make sure you have a CubicWeb instance running with the
+[API cube](https://forge.extranet.logilab.fr/cubicweb/cubes/api).
+
+## Usage
+
+This library exposes a `Client` class used to send requests to the API.
+This class requires the URL to your CubicWeb instance API endpoint
+(eg: `https://example.com/api`).
+
+```js
+const client = new Client("https://example.com/api")
+```
+
+**⚠️ Real API routes include the API version in the URL (eg: `v1`),
+but it must not appear here. The API version number will be automatically set by the client.**
+
+For example, if you used `https://example.com/api/v1/schema` to retrieve your instance schema,
+simply pass `https://example.com/api` to the client,
+it will automatically add `/v1` on each request.
+
+Your client object can then be used to send requests to the API.
+
+See the [Client documentation](https://cubicweb.pages.logilab.fr/cubicwebjs/client/classes/Client.html) for more information.
+
+### Example
+
+The following example tries to log in a user then performs some operations on the instance.
+
+```js
+client
+  .login("login", "password")
+  // Login was successful
+  .then(() => {
+    // Retrieve the instance's schema
+    client
+      .schema()
+      .then((schema) => {
+        console.log("Found the instance's schema:");
+        console.log(schema);
+      })
+      .catch((e) => {
+        console.error("There was an error while fetching the schema:");
+        console.error(e);
+      });
+
+    // Execute an RQL query
+    client
+      .execute("Any X Where X eid 5")
+      .then((resultSet) => {
+        console.log("RQL request was successul and returned:");
+        console.log(resultSet);
+      })
+      .catch((e) => {
+        console.error("There was an error processing the RQL request:");
+        console.error(e);
+      });
+
+    // Execute a series of request in a transaction
+    client
+      .transaction(async (tr) => {
+        const insertResult = await tr.execute(
+          `INSERT Person X: X name "test"`
+        );
+        const insertedEid = insertResult?.[0]?.[0];
+        if (insertedEid != null) {
+          return tr.execute(`Any X Where X eid %(created_eid)s`, {
+            created_eid: insertedEid,
+          });
+        } else {
+          throw new Error("Error inserting Person");
+        }
+      })
+      .then((callbackResult) => {
+        console.log("Transaction was successul and the callback returned:");
+        console.log(callbackResult);
+      })
+      .catch((e) => {
+        console.error("There was an error processing the transaction:");
+        console.error(e);
+      });
+  })
+  // Login failed
+  .catch((e) => {
+    console.error("There was an error while loggin in the user:");
+    console.log(e);
+  });
+```
+
+## CORS handling
+
+> Cross-Origin Resource Sharing (CORS) is an HTTP-header based mechanism that allows a server
+> to indicate any origins (domain, scheme, or port) other than its own from which a browser
+> should permit loading resources. -
+> [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+
+If the client is running on a different server from your CubicWeb instance,
+you must authorize the URL the client is running on as well as the `Content-Type` header in your
+[CubicWeb instance's configuration](https://cubicweb.readthedocs.io/en/latest/book/admin/instance-config#cross-origin-resource-sharing).
+
+## Authentication
+
+The API cube uses cookie authentication using [JWT](https://jwt.io).
+A `CW_JWT` [HTTP Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#security) cookie
+will be automatically created by the browser when executing the login request.
+This cookie cannot be accessed by the JavaScript so you will have to implement your own
+logic to save the login state.
+
+If the client is running on a different server from your CubicWeb instance,
+make sure you setup CORS as described above.
+For the login to work, you may also need to modify the cookie sent by the API cube to set
+[`SameSite`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#samesite_attribute)
+to `None`. 
+
+## Using the Schema
+
+This library provides CubicWeb [schema abstraction classes](packages/client/src/schema/Schema.ts). Three classes are available:
+* `Schema` - Global handling of the schema.
+Can be used to query entities and relations.
+* `EntitySchema` - Handling of a single entity type.
+Can be used to query relations and metadata about the entity.
+* `RelationDefinitionSchema` - Handling of a single relation.
+Can be used to retrieve associated entities and metadata the relation.
+
+The `Schema` class is created from the JSON schema returned by the API.
+The `Client.schema()` method takes care of this for you.
+If your schema does not change often, it is recommended to export it using the following command
+(replace `<YOUR_INSTANCE_NAME>` by the name of your instance): 
+
+```bash
+cubicweb-ctl export-schema -f json <YOUR_INSTANCE_NAME>
+``` 
+
+You can then manually create the Schema object by passing your JSON schema to its constructor.
+
+```js
+// Making the request with the client
+const schema = client.schema();
+// Using a local json schema
+const schema = new Schema(your_raw_json_schema);
+```
+`EntitySchema` and `RelationDefinitionSchema` objects should not be created manually.
+These are returned when querying a `Schema` object.
+
+```js
+// Retrieving an entity
+const entitySchema = schema.getEntity("YourEntityType");
+// Retrieving a relation
+const relationDefinitionSchema = schema.matchRelationDefinitions({
+  subject: "YourEntityType",
+  type: "YourRelationType"',
+  object: "YourEntityType2"
+});
+```
+
+See the [documentation](https://cubicweb.pages.logilab.fr/cubicwebjs/client/modules.html) for more information.
+
+## TypeScript support
+
+Both the client and the schema abstraction classes expose TypeScript types.
+
+You can type the Schema class using the TypeScript representation of your instance schema
+to benefit from the strong type inference. You can generate this representation using the command
+(replace `<YOUR_INSTANCE_NAME>` by the name of your instance):
+
+```bash
+cubicweb-ctl export-schema -f typescript <YOUR_INSTANCE_NAME>
+``` 
+
+This command will generate a file `schema.ts` containing the typings.
+You can then include it in your project. When using this generated type,
+the TS engine will be able to detect invalid entity types and relations.
+
+**⚠️ You cannot type the schema when using the `client.schema()` method.
+This is intended to prevent errors if the JSON schema changes and not the TS schema.**
+You must export both the JSON schema and TypeScript schema to use the typings. 
+
+```js
+// Type the schema when creating from a local JSON schema
+const schema = new Schema<InstanceSchema["entities"], InstanceSchema["relations_definitions"]>(your_raw_json_schema);
+
+// TS will complain it cannot assign type 'never'. This means your entity does not exist.
+const entity = schema.getEntity("InvalidEntityType");
+// TS will be happy and your entity will have the type 'ValidEntityType'.
+const entity = schema.getEntity("ValidEntityType");
+```
+
+

package/lib/schema/raw/Constraints.d.ts

@@ -13,7 +13,9 @@ export declare type ConstraintOperator = ">" | ">=" | "<" | "<=";
  * THe type of a constraint message when one is present.
  */
 declare type ConstraintMessage = string | null;
-export declare type UniqueConstraint = ConstraintBase<"UniqueConstraint", null>;
+export declare type UniqueConstraint = ConstraintBase<"UniqueConstraint", {
+    msg: ConstraintMessage;
+}>;
 export declare type SizeConstraint = ConstraintBase<"SizeConstraint", {
     min: number | null;
     max: number | null;
@@ -46,13 +48,18 @@ export declare type RQLVocabularyConstraint = ConstraintBase<"RQLVocabularyConst
     expression: string;
     mainvars: string[];
 }>;
+export declare type RQLConstraint = ConstraintBase<"RQLConstraint", {
+    expression: string;
+    mainvars: string[];
+    msg: ConstraintMessage;
+}>;
 /**
  * Type representing all possible constraints for attributes.
  */
-export declare type AttributeConstraint = Readonly<UniqueConstraint | SizeConstraint | RegexpConstraint | BoundaryConstraint | IntervalBoundConstraint | StaticVocabularyConstraint | FormatConstraint>;
+export declare type AttributeConstraint = Readonly<UniqueConstraint | SizeConstraint | RegexpConstraint | BoundaryConstraint | IntervalBoundConstraint | StaticVocabularyConstraint | FormatConstraint | RQLConstraint>;
 /**
  * Type representing all possible constraints for relations.
  */
-export declare type RelationConstraint = Readonly<RQLVocabularyConstraint>;
+export declare type RelationConstraint = Readonly<RQLVocabularyConstraint | RQLConstraint>;
 export {};
 //# sourceMappingURL=Constraints.d.ts.map

package/lib/schema/raw/Constraints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Constraints.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/Constraints.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,aAAK,cAAc,CACjB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,IACtC;IACF,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,CAAC,CAAC;CACV,CAAC;AAEF;;GAEG;AACH,oBAAY,kBAAkB,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,aAAK,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvC,oBAAY,gBAAgB,GAAG,cAAc,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;AAExE,oBAAY,cAAc,GAAG,cAAc,CACzC,gBAAgB,EAChB;IAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CACnE,CAAC;AAEF,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC1D,CAAC;AAEF,oBAAY,kBAAkB,GAAG,cAAc,CAC7C,oBAAoB,EACpB;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC5E,CAAC;AACF,oBAAY,uBAAuB,GAAG,cAAc,CAClD,yBAAyB,EACzB;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC7E,CAAC;AAEF,oBAAY,0BAA0B,GAAG,cAAc,CACrD,4BAA4B,EAC5B;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC7C,CAAC;AAEF,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IACE,MAAM,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAClE,GAAG,EAAE,iBAAiB,CAAC;CACxB,CACF,CAAC;AAEF,oBAAY,uBAAuB,GAAG,cAAc,CAClD,yBAAyB,EACzB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAC3C,CAAC;AAEF;;GAEG;AACH,oBAAY,mBAAmB,GAAG,QAAQ,CACtC,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,0BAA0B,GAC1B,gBAAgB,CACnB,CAAC;AAEF;;GAEG;AACH,oBAAY,kBAAkB,GAAG,QAAQ,CAAC,uBAAuB,CAAC,CAAC"}
+{"version":3,"file":"Constraints.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/Constraints.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,aAAK,cAAc,CACjB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,IACtC;IACF,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,CAAC,CAAC;CACV,CAAC;AAEF;;GAEG;AACH,oBAAY,kBAAkB,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,aAAK,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvC,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IAAE,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC3B,CAAC;AAEF,oBAAY,cAAc,GAAG,cAAc,CACzC,gBAAgB,EAChB;IAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CACnE,CAAC;AAEF,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC1D,CAAC;AAEF,oBAAY,kBAAkB,GAAG,cAAc,CAC7C,oBAAoB,EACpB;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC5E,CAAC;AACF,oBAAY,uBAAuB,GAAG,cAAc,CAClD,yBAAyB,EACzB;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC7E,CAAC;AAEF,oBAAY,0BAA0B,GAAG,cAAc,CACrD,4BAA4B,EAC5B;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC7C,CAAC;AAEF,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IACE,MAAM,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAClE,GAAG,EAAE,iBAAiB,CAAC;CACxB,CACF,CAAC;AAEF,oBAAY,uBAAuB,GAAG,cAAc,CAClD,yBAAyB,EACzB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAC3C,CAAC;AAEF,oBAAY,aAAa,GAAG,cAAc,CACxC,eAAe,EACf;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CACnE,CAAC;AAEF;;GAEG;AACH,oBAAY,mBAAmB,GAAG,QAAQ,CACtC,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,0BAA0B,GAC1B,gBAAgB,GAChB,aAAa,CAChB,CAAC;AAEF;;GAEG;AACH,oBAAY,kBAAkB,GAAG,QAAQ,CACvC,uBAAuB,GAAG,aAAa,CACxC,CAAC"}

package/lib/schema/raw/RelationDefinitions.d.ts

@@ -60,13 +60,17 @@ interface TZDatetimeBuildObj extends BuildObjBase<"TZDatetime"> {
 interface IntervalBuildObj extends BuildObjBase<"Interval"> {
     default: unknown;
 }
+interface CustomBuildObj<T extends string> extends BuildObjBase<T> {
+    type: T;
+    default: unknown;
+}
 /**
  * Type allowing to link the type of an object to the type of their default values in a
  * relation definition. It only works for final relations using primitive types.
  *
  * @internal
  */
-export declare type BuildObj = Readonly<StringBuildObj | PasswordBuildObj | BytesBuildObj | IntBuildObj | BigIntBuildObj | FloatBuildObj | BooleanBuildObj | DecimalBuildObj | DateBuildObj | TimeBuildObj | DatetimeBuildObj | TZTimeBuildObj | TZDatetimeBuildObj | IntervalBuildObj>;
+export declare type BuildObj = Readonly<StringBuildObj | PasswordBuildObj | BytesBuildObj | IntBuildObj | BigIntBuildObj | FloatBuildObj | BooleanBuildObj | DecimalBuildObj | DateBuildObj | TimeBuildObj | DatetimeBuildObj | TZTimeBuildObj | TZDatetimeBuildObj | IntervalBuildObj | CustomBuildObj<string>>;
 /**
  * Type representing the possible options for an attribute.
  */

package/lib/schema/raw/RelationDefinitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RelationDefinitions.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/RelationDefinitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RelationDefinitions.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/RelationDefinitions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -2,12 +2,13 @@
   "name": "@cubicweb/client",
   "description": "Official JS client for CubicWeb API",
   "author": "Logilab",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "license": "LGPL-3.0-or-later",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {
-    "build": "tsc  --project tsconfig.build.json"
+    "build": "tsc  --project tsconfig.build.json",
+    "docs": "typedoc"
   },
   "repository": {
     "type": "hg",
@@ -22,5 +23,9 @@
     "lib/**",
     "src/**",
     "!**/__tests__/**"
-  ]
-}
+  ],
+  "devDependencies": {
+    "typedoc": "^0.23.18",
+    "typescript": "^4.8.4"
+  }
+}

package/src/schema/raw/Constraints.ts

@@ -19,7 +19,10 @@ export type ConstraintOperator = ">" | ">=" | "<" | "<=";
  */
 type ConstraintMessage = string | null;
 
-export type UniqueConstraint = ConstraintBase<"UniqueConstraint", null>;
+export type UniqueConstraint = ConstraintBase<
+  "UniqueConstraint",
+  { msg: ConstraintMessage }
+>;
 
 export type SizeConstraint = ConstraintBase<
   "SizeConstraint",
@@ -58,6 +61,11 @@ export type RQLVocabularyConstraint = ConstraintBase<
   { expression: string; mainvars: string[] }
 >;
 
+export type RQLConstraint = ConstraintBase<
+  "RQLConstraint",
+  { expression: string; mainvars: string[]; msg: ConstraintMessage }
+>;
+
 /**
  * Type representing all possible constraints for attributes.
  */
@@ -69,9 +77,12 @@ export type AttributeConstraint = Readonly<
   | IntervalBoundConstraint
   | StaticVocabularyConstraint
   | FormatConstraint
+  | RQLConstraint
 >;
 
 /**
  * Type representing all possible constraints for relations.
  */
-export type RelationConstraint = Readonly<RQLVocabularyConstraint>;
+export type RelationConstraint = Readonly<
+  RQLVocabularyConstraint | RQLConstraint
+>;

package/src/schema/raw/RelationDefinitions.ts

@@ -78,6 +78,11 @@ interface IntervalBuildObj extends BuildObjBase<"Interval"> {
   default: unknown;
 }
 
+interface CustomBuildObj<T extends string> extends BuildObjBase<T> {
+  type: T;
+  default: unknown;
+}
+
 /**
  * Type allowing to link the type of an object to the type of their default values in a
  * relation definition. It only works for final relations using primitive types.
@@ -99,6 +104,7 @@ export type BuildObj = Readonly<
   | TZTimeBuildObj
   | TZDatetimeBuildObj
   | IntervalBuildObj
+  | CustomBuildObj<string>
 >;
 
 /**