Uttori Storage Provider - JSON File

Uttori Storage Provider using JSON files on disk.

This repo exports both a Uttori Plugin compliant Plugin class as well as the underlying StorageProvider class.

Install

npm install --save @uttori/storage-provider-json-file

Config

{
  contentDirectory: '',
  historyDirectory: '',
  extension: 'json',
  spacesDocument: null,
  spacesHistory: null,
  updateTimestamps: true,
  useHistory: true,
  // Registration Events
  events: {
    add: ['storage-add'],
    delete: ['storage-delete'],
    get: ['storage-get'],
    getHistory: ['storage-get-history'],
    getRevision: ['storage-get-revision'],
    getQuery: ['storage-query'],
    update: ['storage-update'],
    validateConfig: ['validate-config'],
  },
}

Example

// When part of UttoriWiki:
import { Plugin as StorageProviderJSON } from '@uttori/storage-provider-json-file';

// When stand alone:
import StorageProvider from '@uttori/storage-provider-json-file';

const s = new StorageProvider({
  contentDirectory: 'example/content',
  historyDirectory: 'example/history',
  extension: 'json',
  spacesDocument: null,
  spacesHistory: null,
});
await s.add({
  title: 'Example Title',
  slug: 'example-title',
  content: '## Example Title',
  html: '',
  updateDate: 1459310452001,
  createDate: 1459310452001,
  tags: ['Example Tag'],
  customData: {
    keyA: 'value-a',
    keyB: 'value-b',
    keyC: 'value-c',
  },
});
const results = await s.getQuery('SELECT tags FROM documents WHERE slug IS_NOT_NULL ORDER BY slug ASC LIMIT 1');
➜  results === [
      { tags: ['Example Tag'] },
    ]
const results = await s.getQuery('SELECT COUNT(*) FROM documents WHERE slug IS_NOT_NULL ORDER BY RANDOM ASC LIMIT -1');
➜  results === 1

API Reference

Classes

Typedefs

StorageProvider

Storage for Uttori documents using JSON files stored on the local file system.

Kind: global class
Properties

| Name | Type | Description | | --- | --- | --- | | config | StorageProviderConfig | The configuration object. | | documents | Record.<string, UttoriDocument> | The collection of documents where the slug is the key and the value is the document. |

• StorageProvider
  • new StorageProvider(config)
  • instance
    • .documents : Record.<string, UttoriDocument>
    • .all ⇒ Promise.<Record.<string, UttoriDocument>>
    • .getQuery ⇒ Promise.<(Array.<UttoriDocument>|number)>
    • .get ⇒ Promise.<(UttoriDocument|undefined)>
    • .add
    • .updateValid ℗
    • .update
    • .delete
    • .getHistory ⇒ Promise.<Array.<string>>
    • .getRevision ⇒ Promise.<(UttoriDocument|undefined)>
    • .updateHistory
  • static
    • .ensureDirectory(directory)

new StorageProvider(config)

Creates an instance of StorageProvider.

| Param | Type | Description | | --- | --- | --- | | config | StorageProviderConfig | A configuration object. |

Example (Init StorageProvider)

const storageProvider = new StorageProvider({ contentDirectory: 'content', historyDirectory: 'history', spacesDocument: 2 });

storageProvider.documents : Record.<string, UttoriDocument>

The collection of documents where the slug is the key and the value is the document.

Kind: instance property of StorageProvider

storageProvider.all ⇒ Promise.<Record.<string, UttoriDocument>>

Returns all documents.

Kind: instance property of StorageProvider
Returns: Promise.<Record.<string, UttoriDocument>> - All documents.
Example

storageProvider.all();
➜ { first-document: { slug: 'first-document', ... }, ...}

storageProvider.getQuery ⇒ Promise.<(Array.<UttoriDocument>|number)>

Returns all documents matching a given query.

Kind: instance property of StorageProvider
Returns: Promise.<(Array.<UttoriDocument>|number)> - Promise object represents all matching documents.

| Param | Type | Description | | --- | --- | --- | | query | string | The conditions on which documents should be returned. |

storageProvider.get ⇒ Promise.<(UttoriDocument|undefined)>

Returns a document for a given slug.

Kind: instance property of StorageProvider
Returns: Promise.<(UttoriDocument|undefined)> - Promise object represents the returned UttoriDocument.

| Param | Type | Description | | --- | --- | --- | | slug | string | The slug of the document to be returned. |

storageProvider.add

Saves a document to the file system.

Kind: instance property of StorageProvider

| Param | Type | Description | | --- | --- | --- | | document | UttoriDocument | The document to be added to the collection. |

storageProvider.updateValid ℗

Updates a document and saves to the file system.

Kind: instance property of StorageProvider
Access: private

| Param | Type | Description | | --- | --- | --- | | document | UttoriDocument | The document to be updated in the collection. | | originalSlug | string | The original slug identifying the document, or the slug if it has not changed. |

storageProvider.update

Updates a document and figures out how to save to the file system.

Kind: instance property of StorageProvider

| Param | Type | Description | | --- | --- | --- | | params | object | The params object. | | params.document | UttoriDocument | The document to be updated in the collection. | | params.originalSlug | string | The original slug identifying the document, or the slug if it has not changed. |

storageProvider.delete

Removes a document from the file system.

Kind: instance property of StorageProvider

| Param | Type | Description | | --- | --- | --- | | slug | string | The slug identifying the document. |

storageProvider.getHistory ⇒ Promise.<Array.<string>>

Returns the history of edits for a given slug.

Kind: instance property of StorageProvider
Returns: Promise.<Array.<string>> - Promise object represents the returned history.

| Param | Type | Description | | --- | --- | --- | | slug | string | The slug of the document to get history for. |

storageProvider.getRevision ⇒ Promise.<(UttoriDocument|undefined)>

Returns a specifc revision from the history of edits for a given slug and revision timestamp.

Kind: instance property of StorageProvider
Returns: Promise.<(UttoriDocument|undefined)> - Promise object represents the returned revision of the document.

| Param | Type | Description | | --- | --- | --- | | params | object | The params object. | | params.slug | string | The slug of the document to be returned. | | params.revision | string | number | The unix timestamp of the history to be returned. |

storageProvider.updateHistory

Updates History for a given slug, renaming the store file and history directory as needed.

Kind: instance property of StorageProvider

| Param | Type | Description | | --- | --- | --- | | slug | string | The slug of the document to update history for. | | content | string | The revision of the document to be saved. | | [originalSlug] | string | The original slug identifying the document, or the slug if it has not changed. |

StorageProvider.ensureDirectory(directory)

Ensure a directory exists, and if not create it.

Kind: static method of StorageProvider

| Param | Type | Description | | --- | --- | --- | | directory | string | The directory to ensure exists. |

UttoriDocument

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | [slug] | string | The unique identifier for the document. | | [createDate] | number | Date | The creation date of the document. | | [updateDate] | number | Date | The last date the document was updated. |

StorageProviderConfig

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | contentDirectory | string | The directory to store documents. | | historyDirectory | string | The directory to store document histories. | | [extension] | string | The file extension to use for file. | | [updateTimestamps] | boolean | Should update times be marked at the time of edit. | | [useHistory] | boolean | Should history entries be created. | | [useCache] | boolean | Should we cache files in memory? | | [spacesDocument] | number | The spaces parameter for JSON stringifying documents. | | [spacesHistory] | number | The spaces parameter for JSON stringifying history. | | [events] | Record.<string, Array.<string>> | The events to listen for. |

Tests

To run the test suite, first install the dependencies, then run npm test:

npm install
npm test
DEBUG=Uttori* npm test

Contributors

• Matthew Callis

License

• MIT