# websocket-foundation

> Socket.io & mongoDB based websocket server foundation

Latest version **0.0.17** (published 2023-04-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install websocket-foundation
pnpm add websocket-foundation
yarn add websocket-foundation
bun add websocket-foundation
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.17 |
| Published | 2023-04-16 |
| First published | 2022-04-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 14 |
| Unpacked size | 60 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Ioannis Pourliotis |
| Maintainers | pheysx |

## Links

- npm: https://www.npmjs.com/package/websocket-foundation
- Repository: https://github.com/PheysX/websocket-foundation
- Homepage: https://github.com/PheysX/websocket-foundation#readme
- Issues: https://github.com/PheysX/websocket-foundation/issues
- npm.io page: https://npm.io/package/websocket-foundation

## Dependencies (14)

- [ajv](https://npm.io/package/ajv.md) ^8.12.0
- [eiows](https://npm.io/package/eiows.md) ^4.1.3
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [npmlog](https://npm.io/package/npmlog.md) ^7.0.1
- [mongodb](https://npm.io/package/mongodb.md) ^5.1.0
- [date-fns](https://npm.io/package/date-fns.md) ^2.29.3
- [socket.io](https://npm.io/package/socket.io.md) ^4.6.1
- [ajv-errors](https://npm.io/package/ajv-errors.md) ^3.0.0
- [bufferutil](https://npm.io/package/bufferutil.md) ^4.0.7
- [ajv-formats](https://npm.io/package/ajv-formats.md) ^2.1.1
- [ajv-bsontype](https://npm.io/package/ajv-bsontype.md) ^1.0.7
- [ajv-keywords](https://npm.io/package/ajv-keywords.md) ^5.1.0
- [utf-8-validate](https://npm.io/package/utf-8-validate.md) ^5.0.10
- [@socket.io/admin-ui](https://npm.io/package/@socket.io/admin-ui.md) ^0.5.1

## Recent versions

- 0.0.17 (latest) — 2023-04-16
- 0.0.16 — 2023-04-11
- 0.0.15 — 2023-01-08
- 0.0.14 — 2022-11-20
- 0.0.13 — 2022-11-20
- 0.0.12 — 2022-11-05
- 0.0.11 — 2022-10-28
- 0.0.10 — 2022-06-15
- 0.0.9 — 2022-06-07
- 0.0.8 — 2022-05-29
- 0.0.7 — 2022-05-29
- 0.0.6 — 2022-05-29
- 0.0.5 — 2022-05-27
- 0.0.4 — 2022-04-23
- 0.0.3 — 2022-04-22
- … 2 more at https://npm.io/package/websocket-foundation/versions

## README

# websocket-foundation

[Socket.io](https://socket.io) & [mongoDB](https://www.mongodb.com/) based websocket server foundation.

## Permissions

### Default permissions

| Operation | Actions                  |
|-----------|--------------------------|
| Read      | `search`,`join`, `leave` |
| Write     | `replace`, `update`      |
| create    | `create`                 |
| delete    | `delete`                 |

## Entities

Every entity needs a schema to pass the validation step. The Schema is based
on [Ajv JSON schema validator](https://github.com/ajv-validator/ajv).

The SocketAccess checks whether the entities exist and create collections if they don't.
**MongoDB collections are never deleted when you remove existing entities.**

### Default entities

| Entity      | Schema                                                                                                                   |
|-------------|--------------------------------------------------------------------------------------------------------------------------|
| user        | [UserSchema](https://github.com/PheysX/websocket-foundation/blob/main/src/Validation/Schema/UserSchema.js)               |
| aclRole     | [AclRoleSchema](https://github.com/PheysX/websocket-foundation/blob/main/src/Validation/Schema/AclRoleSchema.js)         |
| userAclRole | [UserAclRoleSchema](https://github.com/PheysX/websocket-foundation/blob/main/src/Validation/Schema/UserAclRoleSchema.js) |

## Socket Access

All generated events expect an authentication. Authenticate yourself via `user:login` with credentials or userToken:

```
{
    "username": "",
    "password": ""
}
```

```
{
    "userToken": ""
}
```

| Trigger Event | Result Event         | Error Event         |
|---------------|----------------------|---------------------|
| `user:login`  | `user:login:success` | `user:login:failed` |

---

# Events

The SocketAccess will automatically generate events for your entities in combination with all of your operations and
actions.

## Example

You are creating a new entity `document`. The system will create events to communicate with the socket.

| Trigger Event            | Result Event        | Error Event              | Additional entity room events    |
|--------------------------|---------------------|--------------------------|----------------------------------|
| `document:read:search`   | `document:found`    | `document:search:error`  | -                                |
| `document:read:join`     | `client:update`     | -                        | `client:joined`, `client:update` |
| `document:read:leave`    | -                   | -                        | `client:leaved`                  |
| `document:write:replace` | `document:replaced` | `document:replace:error` | `updated`                        |
| `document:write:update`  | `document:updated`  | `document:update:error`  | `updated`                        |
| `document:create:create` | `document:created`  | `document:create:error`  | -                                |
| `document:delete:delete` | `document:deleted`  | `document:delete:error`  | `deleted`                        |

## Actions

### `search`

Search for specific ids or with
multiple [mongoDB](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/) `AND` filters.

```
{
    "ids": [],
    "limit": 50,
    "offset": 0,
    "sort": {},
    "filter": [
        {
            "key": "active",
            "value": true
        }
    ],
    "associations": {}
}
```

### `join`, `leave`:

Just add the specific mongoDB document `_id` to the payload you want to join/leave.

### `create`:

Expects an object payload with your entity required data.

```
{
    "_id": "6948DF80-14BD-4E04-8842-7668D9C001F1",
    "username": "test",
    "password": "alreadyHashedPassword",
    "firstName": "firstName",
    "lastName": "lastName",
    "email": "test@example.com",
    "active": true,
    "admin": true
}
```

### `delete`:

Expects an array payload with ids.

```
{
    "ids": [
        "6948DF80-14BD-4E04-8842-7668D9C001F1",
        "6948DF80-14BD-4E04-8842-7668D9C001F2",
        "6948DF80-14BD-4E04-8842-7668D9C001F3"
    ]
}
```

### `replace`, `update`:

`Replace` is replacing the whole collection entry, `update` is updating specific fields. Expects an object payload with
your entity update/replace required data.

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