o.js

o.js provides a fluent API for standard OData CRUD operations. The following examples use async/await syntax.

Create (POST)

const data = { FirstName: 'Bar', LastName: 'Foo', UserName: 'foobar' };
const response = await o('http://my.url').post('User', data).query();

Read (GET)

const response = await o('http://my.url').get('User').query({$filter: `UserName eq 'foobar'`});
// Returns the exact user if one match is found, otherwise an array of users.

Update (PATCH)

const data = { FirstName: 'John' };
const response = await o('http://my.url').patch(`User('foobar')`, data).query();

Delete

const response = await o('http://my.url').delete(`User('foobar')`).query();

// Create
await o('http://my.url').post('User', { FirstName: 'Bar' }).query();

// Read
await o('http://my.url').get('User').query({$filter: `UserName eq 'foobar'`});

// Update
await o('http://my.url').patch(`User('foobar')`, { FirstName: 'John' }).query();

// Delete
await o('http://my.url').delete(`User('foobar')`).query();

The o constructor accepts a rootUrl and an optional config object.

function o(rootUrl: string | URL, config?: OdataConfig | any)

Root URL Strategies

1. Direct Query: Pass a full URL to query a specific resource immediately. o('http://my.url/some-resource').query()

2. Reusable Handler: Create a handler with a rootUrl in the config to avoid repeating the base URL. const oHandler = o('', { rootUrl: 'http://my.url' }); oHandler.get('some-resource').query(); // requests http://my.url/some-resource

3. Merged Path: If a rootUrl is provided as the first argument AND in the config, they are merged. const oHandler = o('v1', { rootUrl: 'http://my.url' }); oHandler.get('some-resource').query(); // requests http://my.url/v1/some-resource

4. Browser Relative: In a browser, if only a path is provided, it attempts to use the current browser URL. const oHandler = o('v1'); // requests http://[current-url]/v1/some-resource

const oHandler = o('', { rootUrl: 'http://my.url' });
oHandler.get('some-resource').query().then();

You can pass OData query parameters directly as an object to .query() or .fetch(). These are attached as URLSearchParams.

Supported Parameters

• $filter: string
• $orderby: string
• $expand: string
• $select: string
• $skip: number
• $top: number
• $count: boolean (adds inline count metadata)
• $search: string
• $format: string
• $compute: string
• $index: number
• [key: string]: any: allows any additional OData parameters.

Using odata-query

Since version 2.0.0, you can use the odata-query library to build complex filters.

import buildQuery from 'odata-query'

const filter = { not: { and: [{ SomeProp: 1 }, { AnotherProp: 2 }] } };

// Option 1: Pass buildQuery result to .query()
oHandler.get('People').query(buildQuery({ filter }));

// Option 2: Append buildQuery result to the resource path
oHandler.get('People' + buildQuery({ filter, key: 1, top: 10 })).query();

import buildQuery from 'odata-query'

const filter = { not: { and:[ { SomeProp: 1 }, { AnotherProp: 2 } ] } };

// Using only filter in query()
oHandler.get('People')
  .query(buildQuery({ filter }))
  .then((filteredPeople) => {});

The OdataBatchConfig interface allows you to configure experimental batch request behavior. This is passed via the batch property in the main OdataConfig object.

Available options:

• endpoint: The specific endpoint for batch operations.
• headers: Custom Headers to include in the batch request.
• boundaryPrefix: A prefix for the multipart boundary.
• useChangset: Boolean indicating whether to use a changeset within the batch.
• changsetBoundaryPrefix: A prefix for the changeset boundary.
• useRelativeURLs: When truthy, relative URLs will be used within the batch elements.

import { OdataConfig } from 'o.js';

const config: OdataConfig = {
  rootUrl: 'https://api.example.com/odata',
  fragment: 'value',
  onStart: () => null,
  onFinish: () => null,
  onError: () => null,
  batch: {
    useChangset: true,
    useRelativeURLs: true,
    boundaryPrefix: 'o_js_batch',
    changsetBoundaryPrefix: 'o_js_changeset'
  }
};