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

{
  content_directory: '',
  history_directory: '',
  extension: 'json',
  spaces_document: null,
  spaces_history: null,
  update_timestamps: true,
  use_history: 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';
// or
const { Plugin: StorageProviderJSON } = require('@uttori/storage-provider-json-file');

// When stand alone:
import StorageProvider from '@uttori/storage-provider-json-file';
// or
const { StorageProvider } = require('@uttori/storage-provider-json-file');
const s = new StorageProvider({
  content_directory: 'example/content',
  history_directory: 'example/history',
  extension: 'json',
  spaces_document: null,
  spaces_history: 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 = s.getQuery('SELECT COUNT(*) FROM documents WHERE slug IS_NOT_NULL ORDER BY RANDOM ASC LIMIT -1');
➜  results === 1

API Reference

Classes

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

Functions

debug() : function

Typedefs

UttoriDocument

StorageProvider

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

Kind: global class
Properties

Name	Type	Default	Description
config	`object`		The configuration object.
config.content_directory	`string`		The directory to store documents.
config.history_directory	`string`		The directory to store document histories.
[config.extension]	`string`	`"'json'"`	The file extension to use for file, name of the employee.
[config.spaces_document]	`number`		The spaces parameter for JSON stringifying documents.
[config.spaces_history]	`number`		The spaces parameter for JSON stringifying history.
documents	`object`		The collection of documents where the slug is the key and the value is the document.

StorageProvider
- new StorageProvider(config)
- .all() ⇒ object
- .getQuery(query) ⇒ Promise.<(Array.<UttoriDocument>|number)>
- .get(slug) ⇒ Promise.<(UttoriDocument|undefined)>
- .add(document)
- .updateValid(document, originalSlug) ℗
- .update(params)
- .delete(slug)
- .getHistory(slug) ⇒ Promise.<Array.<string>>
- .getRevision(params) ⇒ Promise.<(UttoriDocument|undefined)>
- .updateHistory(slug, content, [originalSlug])

new StorageProvider(config)

Creates an instance of StorageProvider.

Param	Type	Default	Description
config	`object`		A configuration object.
config.content_directory	`string`		The directory to store documents.
config.history_directory	`string`		The directory to store document histories.
[config.extension]	`string`	`"json"`	The file extension to use for file, name of the employee.
[config.update_timestamps]	`boolean`	`true`	Should update times be marked at the time of edit.
[config.use_history]	`boolean`	`true`	Should history entries be created.
[config.use_cache]	`boolean`	`true`	Should we cache files in memory?
[config.spaces_document]	`number`		The spaces parameter for JSON stringifying documents.
[config.spaces_history]	`number`		The spaces parameter for JSON stringifying history.

Example (Init StorageProvider)

const storageProvider = new StorageProvider({ content_directory: 'content', history_directory: 'history', spaces_document: 2 });

storageProvider.all() ⇒ `object`

Returns all documents.

Kind: instance method of StorageProvider
Returns: object - All documents.
Example

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

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

Returns all documents matching a given query.

Kind: instance method 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(slug) ⇒ `Promise.<(UttoriDocument|undefined)>`

Returns a document for a given slug.

Kind: instance method 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(document)

Saves a document to the file system.

Kind: instance method of StorageProvider

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

storageProvider.updateValid(document, originalSlug) ℗

Updates a document and saves to the file system.

Kind: instance method 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(params)

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

Kind: instance method 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(slug)

Removes a document from the file system.

Kind: instance method of StorageProvider

Param	Type	Description
slug	`string`	The slug identifying the document.

storageProvider.getHistory(slug) ⇒ `Promise.<Array.<string>>`

Returns the history of edits for a given slug.

Kind: instance method 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(params) ⇒ `Promise.<(UttoriDocument|undefined)>`

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

Kind: instance method 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(slug, content, [originalSlug])

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

Kind: instance method 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.

debug() : `function`

Kind: global function

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.

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

npm