# @restorecommerce/resource-base-interface

> Restorecommerce Resource Base Interface

Latest version **1.10.3** (published 2026-08-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @restorecommerce/resource-base-interface
pnpm add @restorecommerce/resource-base-interface
yarn add @restorecommerce/resource-base-interface
bun add @restorecommerce/resource-base-interface
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.10.3 |
| Published | 2026-08-05 |
| First published | 2020-01-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 20.0.0 |
| Dependencies | 10 |
| Unpacked size | 213.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | n-fuse GmbH |
| Maintainers | vanthome, akumarnpm, dani723, vilsol, radu1990 |
| Keywords | restore, commerce, resource, base, interface |

## Links

- npm: https://www.npmjs.com/package/@restorecommerce/resource-base-interface
- Repository: https://github.com/restorecommerce/resource-base-interface
- npm.io page: https://npm.io/package/@restorecommerce/resource-base-interface

## Dependencies (10)

- [redis](https://npm.io/package/redis.md) 4.7.0
- [remeda](https://npm.io/package/remeda.md) 2.39.0
- [@restorecommerce/scs-jobs](https://npm.io/package/@restorecommerce/scs-jobs.md) ^0.3.3
- [@restorecommerce/acs-client](https://npm.io/package/@restorecommerce/acs-client.md) ^3.2.3
- [nice-grpc-server-reflection](https://npm.io/package/nice-grpc-server-reflection.md) 3.0.5
- [@restorecommerce/chassis-srv](https://npm.io/package/@restorecommerce/chassis-srv.md) ^1.9.3
- [@restorecommerce/grpc-client](https://npm.io/package/@restorecommerce/grpc-client.md) ^2.3.3
- [@restorecommerce/kafka-client](https://npm.io/package/@restorecommerce/kafka-client.md) ^1.4.3
- [@restorecommerce/service-config](https://npm.io/package/@restorecommerce/service-config.md) ^1.2.3
- [@restorecommerce/rc-grpc-clients](https://npm.io/package/@restorecommerce/rc-grpc-clients.md) ^5.2.3

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 1.10.3 (latest) — 2026-08-05
- 1.10.2 — 2026-07-03
- 1.10.1 — 2026-06-16
- 1.10.0 — 2026-06-12
- 1.9.22 — 2026-05-27
- 1.9.21 — 2026-05-12
- 1.9.20 — 2026-05-11
- 1.9.19 — 2026-04-07
- 1.9.18 — 2026-03-31
- 1.9.17 — 2026-03-23
- 1.9.16 — 2026-02-17
- 1.9.15 — 2026-02-16
- 1.9.14 — 2026-02-12
- 1.9.13 — 2026-02-09
- 1.9.12 — 2026-02-09
- … 68 more at https://npm.io/package/@restorecommerce/resource-base-interface/versions

## README

# resource-base-interface

[![Version][version]](https://www.npmjs.com/package/@restorecommerce/resource-base-interface)[![Build Status][build]](https://img.shields.io/github/actions/workflow/status/restorecommerce/resource-base-interface/build.yaml?style=flat-square)[![Dependencies][depend]](https://david-dm.org/restorecommerce/resource-base-interface)[![Coverage Status][cover]](https://coveralls.io/github/restorecommerce/resource-base-interface?branch=master)

[version]: http://img.shields.io/npm/v/@restorecommerce/resource-base-interface.svg?style=flat-square
[build]: https://img.shields.io/github/actions/workflow/status/restorecommerce/resource-base-interface/build.yaml?style=flat-square
[depend]: https://img.shields.io/david/restorecommerce/resource-base-interface.svg?style=flat-square
[cover]: http://img.shields.io/coveralls/restorecommerce/resource-base-interface/master.svg?style=flat-square

https://github.com/restorecommerce/notification-srv/actions/workflows/build.yaml[image:https://img.shields.io/github/actions/workflow/status/restorecommerce/notification-srv/build.yaml?style=flat-square[Build Status]]

The `resource-base-interface` describes resource CRUD operations which can be bound to a service. Such operations are described via a [gRPC](https://grpc.io/docs/) interface with the message structures therefore being defined using [Protocol Buffers](https://developers.google.com/protocol-buffers/). This interface can be bound with any protobuf definition as long as it contains the endpoints defined in the [resource-base.proto](https://github.com/restorecommerce/protos/blob/master/io/restorecommerce/resource_base.proto) file (note that any resource message structure can be defined).

The exposed gRPC methods are implemented by the `ServiceBase` object which uses a `ResourceAPI` instance to perform operations with a database provider. The exposed interface is therefore agnostic to a specific database implementation.
However, a valid database provider is required. A set of such providers is implemented in [chassis-srv](https://github.com/restorecommerce/chassis-srv/).
This interface emits resource-related messages to [Apache Kafka](https://kafka.apache.org) which can be enabled or disabled at the `ServiceBase`'s constructor.


Methods for managing and traversing graph databases are supported for the [`ArangoDB provider`](https://docs.arangodb.com/3.3/HTTP/Gharial/)

## gRPC Interface

This interface describes the following gRPC endpoints for a generic resource of type `Resource`.

`io.restorecommerce.resourcebase.Resource`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | string | optional | identifier for the resource |
| meta | io.restorecommerce.meta.Meta meta | optional | Meta information common to all Restore Commerce resources |
| value | number | optional | value for the resource |
| text | string | optional | textual data for the resource |

### Create

This operation is used for inserting resources to the database.
Requests are performed by providing a list of resources which are returned in the response. A [`meta`](https://github.com/restorecommerce/protos/blob/master/io/restorecommerce/meta.proto) should be present, containing relevant resource ownership information. Timestamps for creation and modification are then appended automatically to this property upon a `Create` request.
The resource is stored as a normal collection document by default.
If there is a [graph configuration](test/cfg/config.json#L11) specified for the resource then it is stored as a vertex collection along with the edge definitions provided in the configuration.

`io.restorecommerce.resourcebase.ResourceList`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| items | [ ] `io.restorecommerce.resourcebase.Resource` | required | list of resources |
| total_count | number | optional | total number of resources |

### Read

This operation returns resources based on provided filter and options.
Requests are performed using `io.restorecommerce.resourcebase.ReadRequest` and responses are a list of resources.

`io.restorecommerce.resourcebase.ReadRequest`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| offset | number | optional | offset of the resource |
| limit | number | optional | limit, default value is `1000` |
| filters | `io.restorecommerce.filter.FilterOp` | optional | nested filters based on field values, multiple filters can be combined with `AND` and `OR` operators  |
| sorts | [ ]`io.restorecommerce.resourcebase.Sort` | optional | sort the resources |
| fields | [ ] `io.restorecommerce.resourcebase.FieldFilter` | optional | fields selector, list of fields to be included or excluded, by default we get all the fields |
| search | [ ]string | optional | word search, not yet implemeneted |
| locales_limiter | [ ]string | optional | querying based on locales, not yet implemented |

`io.restorecommerce.filter.FilterOp`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| filters | `io.restorecommerce.filter.Filter` | optional | nested filters |
| operator | enum | optional | operator `and`, or `or` |

`io.restorecommerce.graph.Filter`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| field | string | required | filter based on field |
| operation | enum | optional | operator `eq`, `lt`, `lte`, `gt`, `gte`, `isEmpty`, `ilike`, `in`, `neq`, default value is `eq` |
| value | string | required | filter based on value |
| type | enum | optional | value type `STRING`, `NUMBER`, `BOOLEAN`, `DATE` or `ARRAY`, default value is `STRING` |
| filters | [ ] `io.restorecommerce.filter.FilterOp` | required | nested filters |

`io.restorecommerce.resourcebase.Sort`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| field | string | optional | field to be sorted upon |
| SortOrder | enum | optional | sorting order, `UNSORTED`, `ASCENDING` or `DESCENDING` |

`io.restorecommerce.resourcebase.FieldFilter`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| name | string | optional | field name |
| include | bool | optional | include or exclude field |

### Update

This operation is used for updating resources in the database.
Requests are performed by providing a list of resources and all updated items are returned within the response. Note that the only required properties on each resource are its `id` and the properties which are meant to be modified.
It is possible to specify in the configuration multiple edge definitions for one vertex. These edges are automatically updated when vertex documents are updated.

### Upsert

This operation is used for updating resources in the database or creating them if they do not exist.
Requests are performed  by providing a resource list, which is returned in the response.

### Delete

This operation is used for deleting resources in the database.
Requests are performed using `io.restorecommerce.resourcebase.DeleteRequest` and responses are `google.protobuf.Empty` messages.
If a graph vertex is deleted, all connected edges are also deleted.

`io.restorecommerce.resourcebase.DeleteRequest`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| collection | string | optional | Name of the target collection |
| ids | [ ]string | optional | List of resource identifiers to be deleted; if empty or not provided, the whole collection is truncated |

### Traversal

This operation is used for traversing graph resource in the database.
Requests are performed using `io.restorecommerce.graph.TraversalRequest` and respone is `io.restorecommerce.graph.TraversalResponse` message.

`io.restorecommerce.graph.TraversalRequest`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| vertices | [ ]`io.restorecommerce.graph.Vertices` | optional | list of vertices for traversal |
| collection | `io.restorecommerce.graph.Collection` | optional | collection data for traversal |
| opts | `io.restorecommerce.graph.Options` | optional | List of options for graph traversal |
| path | bool | optional | if set to `true` only the traversed paths are returned |
| subject | `io.restorecommerce.auth.Subject` | required | Subject details |
| filters | `io.restorecommerce.graph.Filters` | optional | filters |

`io.restorecommerce.graph.Vertices`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| collection_name | string | required | collection name |
| start_vertex_ids | [ ] string | required | list of start vertex ids |

`io.restorecommerce.graph.Collection`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| collection_name | string | required | collection name |
| limit | [ ] number | optional | limit |
| sorts | [ ] `io.restorecommerce.resourcebase.Sort` | optional | sorting based on fields |

`io.restorecommerce.graph.Filters`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| entity | string | optional | entity name |
| edge | string | optional | edge name |
| filters | `io.restorecommerce.graph.Filter` | optional | Filter |
| operator | enum | optional | operator, `and` or `or`, default is `and` |

`io.restorecommerce.graph.Options`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| include_vertexs | [ ] string | optional | list of vertex's to be included in traversal |
| exclude_vertexs | [ ] string | optional | list of vertex's to be excluded in traversal |
| include_edges | [ ] string | optional | list of edge's to be included in traversal |
| exclude_edges | [ ] string | optional | list of edge's to be excluded in traversal |
| direction | enum | optional | direction of traversal, `OUTBOUND` or `INBOUND`, default is `OUTBOUND` |

`io.restorecommerce.graph.TraversalResponse`

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| paths | `google.protobuf.Any` | required | buffered data, contains the list of visited paths |
| data | `google.protobuf.Any` | required | buffered data, contains all the data from the visited vertices |
| operation_status | `io.restorecommerce.status.OperationStatus` | required | operation status |

## Kafka Events

A kafka [`Topic`](https://github.com/restorecommerce/kafka-client/blob/master/src/events/provider/kafka/index.ts) can be provided when instantiating a `ServiceBase`. If `enableEvents` is set to true, a list of events is then emitted to Kafka by this microservice for each document of each CRUD request :
- <ResourceName>Created
- <ResourceName>Read
- <ResourceName>Modified
- <ResourceName>Deleted

The events emitted to Kafka can be used for restoring the system in case of failure by implementing a [command-interface](https://github.com/restorecommerce/chassis-srv/blob/master/command-interface.md) in the used microservice. For usage details please see [command-interface tests](https://github.com/restorecommerce/chassis-srv/blob/master/test/command_test.ts).

## Fields Configuration

It is possible to pass a fields [`configuration object`](test/cfg/config.json#L235) to `ResourceAPI` in order to enable some special field handlers.

### Field Generators

The `strategies` property can be used to specify fields within each resource which should be generated automatically. Such autogeneration feature currently includes UUIDs, timestamps and sequential counters. The latter one is particularly useful for fields such as a customer or an item number, which can have a type of sequential logic. In these cases, a [Redis](https://redis.io/) database is used to generate and read these values efficiently.

### Buffer Fields

Buffer-encoded fields can be decoded before being stored in the database. It is possible to specify within the `bufferFields` property what fields of each resource should be specially handled this way. The values are also encoded into a buffer again when read from the database.

### Required Fields

It is possible to specify which fields are required for each document of each resource on the `requiredFields` config.
An `InvalidArgument` error is thrown if one of these fields is missing when attempting to store a document.

## Development

### Tests

See [tests](test/). To execute the tests a set of _backing services_ are needed.
Refer to [System](https://github.com/restorecommerce/system) repository to start the backing-services before running the tests.

- To run tests

```sh
npm run test
```

## Usage

- Install dependencies

```sh
npm install
```

- Build

```sh
# compile the code
npm run build
```

---
_Source: https://npm.io/package/@restorecommerce/resource-base-interface · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._