# @parameter1/base-cms-db

> The BaseCMS database driver. Requires direct MongoDB access.

Latest version **4.74.0** (published 2024-10-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @parameter1/base-cms-db
pnpm add @parameter1/base-cms-db
yarn add @parameter1/base-cms-db
bun add @parameter1/base-cms-db
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.74.0 |
| Published | 2024-10-29 |
| First published | 2021-01-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 41.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Jacob Bare |
| Maintainers | b77mills, brandonbk, zarathustra323, solocommand |

## Links

- npm: https://www.npmjs.com/package/@parameter1/base-cms-db
- Repository: https://github.com/parameter1/base-cms.git#master
- Homepage: https://github.com/parameter1/base-cms/tree/master#readme
- Issues: https://github.com/parameter1/base-cms/issues
- npm.io page: https://npm.io/package/@parameter1/base-cms-db

## Dependencies (8)

- [mongodb](https://npm.io/package/mongodb.md) ^3.7.3
- [deepmerge](https://npm.io/package/deepmerge.md) ^3.3.0
- [base64-url](https://npm.io/package/base64-url.md) ^2.3.3
- [object-path](https://npm.io/package/object-path.md) ^0.11.8
- [mongodb-extended-json](https://npm.io/package/mongodb-extended-json.md) 1.10.1
- [@parameter1/base-cms-async](https://npm.io/package/@parameter1/base-cms-async.md) ^4.74.0
- [@parameter1/base-cms-utils](https://npm.io/package/@parameter1/base-cms-utils.md) ^4.74.0
- [@parameter1/base-cms-object-path](https://npm.io/package/@parameter1/base-cms-object-path.md) ^4.74.0

## Recent versions

- 4.74.0 (latest) — 2024-10-29
- 4.67.0 — 2024-09-28
- 4.40.3 — 2023-11-02
- 4.5.12 — 2023-02-27
- 4.4.0 — 2023-02-26
- 4.0.2 — 2023-02-21
- 4.0.0 — 2023-02-21
- 4.0.0-beta.0 — 2023-02-20
- 4.0.0-alpha.0 — 2023-02-17
- 3.0.0 — 2022-08-11
- 2.75.1 — 2022-02-10
- 2.75.0 — 2022-02-10
- 2.45.0 — 2021-10-07
- 2.22.2 — 2021-06-03
- 2.5.0 — 2021-03-02
- … 4 more at https://npm.io/package/@parameter1/base-cms-db/versions

## README

# BaseCMS DB
The BaseCMS database driver. Requires direct MongoDB access.

## Installation
```
yarn add @parameter1/base-cms-db
```

## Usage
```js
const { BaseDB, MongoDB } = require('@parameter1/base-cms-db');

// The Base MongoDB url.
const url = 'mongodb://localhost:1234/platform';
const client = new MongoDB.Client(url, {
  useNewUrlParser: true,
});

// Create the instance for the tenant.
// Must pass the MongoDB.Client instance to the constructor.
const base = new BaseDB({
  tenant: 'cygnus_ofcr',
  client,
});

const run = async () => {
  // Find content by ID.
  // If not found, will return `null`
  const content1 = await base.findById('platform.Content', 12345678);

  // Find content by ID, but throw error if not found.
  const content2 = await base.strictFindById('platform.Content', 12345678);

  // Count content records
  const count = await base.count('platform.Content');
};
run();
```

## API
### Instance Methods
All methods return a `Promise` and, as such, can be used within `async` functions. 🤘

#### `base.findById(modelName, id[, options])`
Finds a single document for the provided model name and ID.
```js
const go = async () => {
  const content = await base.findById('platform.Content', 12345678);

  // Only return specific fields
  const content2 = await base.findById('platform.Content', 12345678, {
    projection: { name: 1, published: 1 },
  });
};
go();
```

#### `base.strictFindById(modelName, id[, options])`
Finds a single document for the provided model name and ID. Will throw an error if the document is not found.
```js
const go = async () => {
  // Will throw if not found. Handle in `.catch`, etc.
  const content = await base.strictFindById('platform.Content', 12345678);
};
go().catch(err => console.log(err));
```

#### `base.findOne(modelName[, query][, options])`
Finds a single document for the provided model name and (optional) query criteria.
```js
const go = async () => {
  const content = await base.findOne('platform.Content', {
    _id: 12345678,
    status: 1,
  });

  // Only return specific fields
  const content2 = await base.findOne('platform.Content', {
    _id: 12345678,
    status: 1,
  }, {
    projection: { name: 1, published: 1 },
  });
};
go();
```

#### `base.strictFindOne(modelName[, query][, options])`
Finds a single document for the provided model name and (optional) query criteria. Will throw an error if the document is not found.
```js
const go = async () => {
  // Will throw if not found.
  const content = await base.strictFindOne('platform.Content', {
    _id: 12345678,
    status: 1,
  });
};
go();
```

#### `base.find(modelName[, query][, options])`
Finds a multiple documents for the provided model name and (optional) query criteria. Will return a MongoDB cursor object.
```js
const go = async () => {
  // Will return a MongoDB cursor for iteration.
  const cursor = await base.find('platform.Content', {
    published: { $lte: new Date() },
    status: 1,
  });

  // Apply sorting.
  // Either as an option arg...
  // See http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#find
  const cursor2 = await base.find('platform.Content', {
    published: { $lte: new Date() },
    status: 1,
  }, {
    sort: [['name', 1]],
  });
  // Or directly on the cursor.
  // See http://mongodb.github.io/node-mongodb-native/3.1/api/Cursor.html
  cursor2.sort([['name', -1]]);
};
go();
```

#### `base.count(modelName[, query][, options])`
Counts the number of documents for the provided model name and (optional) query criteria.
```js
const go = async () => {
  // Return number of active content documents.
  const num = await base.count('platform.Content', { status: 1 });
};
go();
```

#### `base.distinct(modelName, field[, query][, options])`
Returns distinct values for the provided model name, key (field name) and (optional) query criteria.
```js
const go = async () => {
  // Return a distinct list of published dates of active content documents.
  const dates = await base.distinct('platform.Content', 'published', { status: 1 });
};
go();
```

#### `base.db(namespace[, options])`
Returns a MongoDB `Db` instance for the provided namespace.
```js
const go = async () => {
  // Get the platform DB instance.
  const db = base.db('platform');
};
go();
```

#### `base.collection(namespace, resource[, options])`
Returns a MongoDB `Collection` instance for the provided namespace and resource
```js
const go = async () => {
  // Get the content collection instance.
  const collection = base.collection('platform', 'Content');
};
go();
```

#### `base.tenant(key)`
Set/change the active tenant. Note: this method does _not_ return a `Promise`.
```js
base.tenant('some_tenant');
```

### Static Methods
Utility/helper methods.

#### `coerceID(id)`
Coerces a string ID to either a MongoDB ObjectID or an integer. If the `id` value is not a string, or does not match the requirements for the above, the `id` value will be returned as-is.
```js
const BaseDB = require('@parameter1/base-cms-db');
const { ObjectID } = require('mongodb');

// Becomes the number `1234`
const id1 = BaseDB.coerceID('1234');

// Becomes ObjectID('5b0d4edb74265bb4c8edc863')
const id2 = BaseDB.coerceID('5b0d4edb74265bb4c8edc863');

// Stays as an ObjectID
const id3 = BaseDB.coerceID(ObjectID('5bbb7920adff35d154b1c099'));

// Is left as-is
const id4 = BaseDB.coerceID('some-value');
```

#### `extractMutationValue(doc, type, field)`
Extracts a mutation value from a document for the provided type and field.
```js
const BaseDB = require('@parameter1/base-cms-db');

// Get the `Website.name` mutation value. Will return `Foo` since the mutation is set.
const doc1 = {
  mutations: {
    Website: {
      name: 'Foo',
    },
  },
};
const websiteName = BaseDB.extractMutationValue(doc, 'Website', 'name');

// Get the `Magazine.name` mutation value. Will return `null` since mutation is not found.
const magazibneName = BaseDB.extractMutationValue(doc, 'Magazine', 'name');
```

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