@cubicweb/client

CubicWeb JS

This library is the CubicWeb JavaScript client used to communicate with instances running with the API cube. It replaces the cwclientlibjs library.

The full documentation is available here.

Installation

CubicWebJS is avalaible from NPM:

# 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.

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).

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 for more information.

Example

The following example tries to log in a user then performs some operations on the instance.

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

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.

Authentication

The API cube uses cookie authentication using JWT. A CW_JWT HTTP Only 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 to None.

Using the Schema

This library provides CubicWeb schema abstraction classes. 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):

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.

// 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.

// Retrieving an entity
const entitySchema = schema.getEntity("YourEntityType");
// Retrieving a relation
const relationDefinitionSchema = schema.matchRelationDefinitions({
subject: "YourEntityType",
type: "YourRelationType"',
object: "YourEntityType2"
});

See the documentation 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):

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.

// 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");

Generated using TypeDoc