# Collections

### Setup

{% code lineNumbers="true" %}

```js
const Collection = require('dubnium/collection');
const collection = new Collection(db, name, schema)
```

{% endcode %}

| Parameter | Type             | About                                                                                                                                                                                                                               |
| --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `db`      | Object           | The database instance this collection is associated with.                                                                                                                                                                           |
| `name`    | String           | The prefix or name of the collection.                                                                                                                                                                                               |
| `schema`  | Object \| String | Schema definition for validating data. Can be: - A string: any non-null value is valid. - An object: keys are field names and values are either expected types (`"string"`, `"number"`, etc.) or `"required"` for mandatory fields. |

## Validate a Record

* If schema is a string, validation passes if `data` is not `undefined` or `null`.
* If schema is an object:
  * Each key in the schema must exist in the data.
  * `"required"` fields must be non-empty.
  * Each field must match the expected type.

{% code lineNumbers="true" %}

```javascript
collection.validate(data)
```

{% endcode %}

**Parameters**

| Name   | Type   | About                 |
| ------ | ------ | --------------------- |
| `data` | Object | The data to validate. |

**Returns**

| Type    | About                                                     |
| ------- | --------------------------------------------------------- |
| Boolean | `true` if the data matches the schema, `false` otherwise. |

Creates a new record in the database after validating it against the schema.

{% code lineNumbers="true" %}

```javascript
collection.create('tag', data)
```

{% endcode %}

**Parameters**

| Name   | Type            | About                             |
| ------ | --------------- | --------------------------------- |
| `tag`  | String          | Unique identifier for the record. |
| `data` | Object \|String | Data to be stored.                |

**Returns**

* A promise resolving to the result of `db.create(tag, data)`

## Full Example

{% code lineNumbers="true" %}

```js
const Collection = require('./Collection');
const db = require('./myDatabase'); // Must implement create(tag, data)

const userSchema = {
  username: 'string',
  email: 'string',
  password: 'required'
};

const users = new Collection(db, 'users', userSchema);

async function addUser() {
  const userData = { username: 'alice', email: 'alice@example.com', password: 'secret' };
  try {
    const result = await users.create('user_1', userData);
    console.log('User created:', result);
  } catch (err) {
    console.error(err);
  }
}

addUser();
```

{% endcode %}