# @frusal/library

> The official library for connecting to frusal.com workspace. Depends on autobahn and rxjs.

Latest version **0.0.33** (published 2020-08-22) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @frusal/library
pnpm add @frusal/library
yarn add @frusal/library
bun add @frusal/library
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.33 |
| Published | 2020-08-22 |
| First published | 2020-04-20 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 580.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | info@frusal.com |
| Maintainers | aelxva |
| Keywords | frusal, frusal-client-library, module |

## Links

- npm: https://www.npmjs.com/package/@frusal/library
- npm.io page: https://npm.io/package/@frusal/library

## Dependencies (2)

- [rxjs](https://npm.io/package/rxjs.md) 6.x.x
- [autobahn](https://npm.io/package/autobahn.md) 20.x.x

## Recent versions

- 0.0.33 (latest) — 2020-08-22
- 0.0.0 — 2020-04-20

## README

# The official library for connecting to frusal.com workspace.

The official library for connecting to frusal.com workspace. Depends on autobahn and rxjs.

🚧 *The project is in development and is not available for general public yet. // 2020-08-22*

It is recommended to use [Frusal CLI] to install and manage declaration schema with this library, though not strictly required.

<details><summary>Choose the right library</summary>

There are three flavours of this library: pre-packaged to be used in a [browser] or run under [node], and not packaged to be used in a more advanced build setups.

| NPM Package | Target Environment | Dependencies | Note |
| --- | --- | --- | --- |
| [@frusal/library-for-browser] | [Browser] | - | Ready to use bundle |
| [@frusal/library-for-node] | [Node] | - | Ready to use bundle |
| [@frusal/library] | *any* | [autobahn], [rxjs] | Flexible |

## Frameworks

For [Angular], [React] and [Vue.js] frameworks, we recommend to use [@frusal/library].

</details>

## Code

### Workspace Schema

The schema (class structure) could be created via frusal.com UI, or programmatically via a script. See this [schema creation script example][Script Schema Example].

### Session and Login

```js
import { session } from '@frusal/library-for-browser';

await session.login({
    loginId: 'john.citizen@example.com',
    password: 'yM8yXA(jMbsUpy,=',
    workspace: 'playground'
});
```

### Stage and Transaction

```js
await session.workspace.withTempStageAsyncExpression(async stage => {
    await stage.transact(async transaction => {
        const fruit = transaction.createEntity(Fruit);
        fruit.name = 'Plum';
    });
});
```

<details><summary>More advanced</summary>

```js
const owner = new Owner();
try {
    const stage = await session.createStage(owner);
    const transaction = this.stage.beginTransaction();

    const actualWorkspace = transaction.getSingletonInstance(ActualWorkspace);
    console.log(`actualWorkspace.name=${actualWorkspace.name}`);

    const plum = await await this.stage.query({ q: 'b0o4cF', type: QPType.BY_ID }).promiseFirstOfType(Fruit);
    plum.delete();

} finally {
    owner.close();
}
```

</details>

### Query

Get all instances of class `Fruit` at indexed store:

```js
const fruits = await this.stage.query({ q: Fruit.id, type: QPType.BY_CLASS_ID }).promiseArray() as Fruit[];
```

There are different queries possible, depends on the underlying store type. There are indexed store and consolidated store. Indexed store, stores entities in separate indexed (Lucene) documents and Consolidated store keeps all entities in one document (as JSON BLOB). As such, large tables which require complex queries should be stored in indexed store (Order, Order Line); and limited row tables like lookups (Product), properties, etc are best stored at a consolidated store.

Default store is configured on per class level.

### Subscriptions

An auto-updating subscription below would make the client to subscribe to the server for live updates. Alternatively, depend on the requirements and performance limitations, `entity.refresh()` can be called at times, or whole `stage` reconstructed - which always takes the fresh values.

Instance level subscription:

```js
fruit.subscribeToChanges(owner, { autoupdate: true, callback: evt => {
    console.log(`Entity ${evt.entity.id} is changed.`);
}});
```

Class level subscription:

```js
Fruit.classSpec.subscribeToCreatedAndDeleted(owner, { autoupdate: true, callback: evt => {
    console.log(`Entity ${evt.entity.id} is ${evt.entity.deleted ? 'deleted' : 'created'}.`);
}});
```

*Note that `classSpec.subscribeToChanges` monitors the class object instance itself (as in class schema model) and has nothing to do with its instances and their changes.*

<details><summary>More advanced</summary>

```js
instance.field_pv.subscribeToChanges(//... field level
instance.subscribeToChanges(//... instance level
classSpec.subscribeToCreatedAndDeleted(//... class level
store.subscribeToChanges(//... store level
```

</details>

## Examples and Tutorials

- [Angular Tutorial]
- [React Tutorial]
- [Node.js Tutorial]

[Frusal CLI]: https://www.npmjs.com/package/frusal

[@frusal/library-for-browser]: https://www.npmjs.com/package/@frusal/library-for-browser
[@frusal/library-for-node]: https://www.npmjs.com/package/@frusal/library-for-node
[@frusal/library]: https://www.npmjs.com/package/@frusal/library

[autobahn]: https://www.npmjs.com/package/autobahn
[rxjs]: https://www.npmjs.com/package/rxjs

[Browser]: https://en.wikipedia.org/wiki/Web_browser
[Node]: https://nodejs.org/
[Angular]: https://angular.io/
[React]: http://reactjs.org/
[Vue.js]: https://vuejs.org/

[Angular Tutorial]: https://github.com/frusal/frusal-tutorial-angular#readme
[React Tutorial]: https://github.com/frusal/frusal-tutorial-react#readme
[Node.js Tutorial]: https://github.com/frusal/frusal-tutorial-node#readme
[Script Schema Example]: https://github.com/frusal/frusal-example-schema-by-javascript#readme

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