@uttori/storage-provider-json-file

Uttori storage provider using JSON files on disk.

Usage no npm install needed!

<script type="module">
  import uttoriStorageProviderJsonFile from 'https://cdn.skypack.dev/@uttori/storage-provider-json-file';
</script>

README

view on npm npm module downloads Build Status Dependency Status Coverage Status Tree-Shaking Support Dependency Count Minified + GZip Minified

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.

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 folder 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

License