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

StorageProvider

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

Typedefs

UttoriDocument

StorageProviderConfig

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