From 08f0a74616c2da024974173b49e6d1a66b230e0e Mon Sep 17 00:00:00 2001 From: Matthew Callis Date: Tue, 3 Sep 2019 14:42:44 -0700 Subject: [PATCH] Update docs --- README.md | 214 ++----------------------------------------------- docs/README.md | 214 ++----------------------------------------------- 2 files changed, 12 insertions(+), 416 deletions(-) diff --git a/README.md b/README.md index f3c1fb7..c612b84 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,8 @@ npm install --save uttori-storage-provider-json-file { content_dir: '', history_dir: '', - data_dir: '', extension: 'json', spaces_document: null, - spaces_data: null, spaces_history: null, } ``` @@ -50,12 +48,7 @@ Storage for Uttori documents using JSON files stored on the local file system. * [new StorageProvider(config)](#new_StorageProvider_new) * [.all()](#StorageProvider+all) ⇒ Promise * [.tags()](#StorageProvider+tags) ⇒ Promise - * [.getTaggedDocuments(tag, [limit], fields)](#StorageProvider+getTaggedDocuments) ⇒ Promise - * [.getRelatedDocuments(document, limit, fields)](#StorageProvider+getRelatedDocuments) ⇒ Promise - * [.getRecentDocuments(limit, fields)](#StorageProvider+getRecentDocuments) ⇒ Promise - * [.getPopularDocuments(limit, fields)](#StorageProvider+getPopularDocuments) ⇒ Promise - * [.getRandomDocuments(limit, fields)](#StorageProvider+getRandomDocuments) ⇒ Promise - * [.augmentDocuments(documents, _fields)](#StorageProvider+augmentDocuments) ⇒ Promise + * [.getQuery(query)](#StorageProvider+getQuery) ⇒ Promise * [.get(slug)](#StorageProvider+get) ⇒ Promise * [.getHistory(slug)](#StorageProvider+getHistory) ⇒ Promise * [.getRevision(slug, revision)](#StorageProvider+getRevision) ⇒ Promise @@ -63,16 +56,7 @@ Storage for Uttori documents using JSON files stored on the local file system. * [.updateValid(document, originalSlug)](#StorageProvider+updateValid) ℗ * [.update(document, originalSlug)](#StorageProvider+update) * [.delete(slug)](#StorageProvider+delete) - * [.storeObject(name, data)](#StorageProvider+storeObject) - * [.updateObject(name, key, value)](#StorageProvider+updateObject) - * [.incrementObject(name, key, [amount])](#StorageProvider+incrementObject) - * [.decrementObject(name, key, [amount])](#StorageProvider+decrementObject) - * [.readObject(name, fallback)](#StorageProvider+readObject) ⇒ Promise.<Object> - * [.readObjectValue(name, key, fallback)](#StorageProvider+readObjectValue) ⇒ Promise.<Object> * [.refresh()](#StorageProvider+refresh) - * [.deleteFile(folder, name)](#StorageProvider+deleteFile) - * [.readFile(folder, name)](#StorageProvider+readFile) ⇒ Object - * [.readFolder(folder)](#StorageProvider+readFolder) ⇒ Array.<string> * [.updateHistory(slug, content, originalSlug)](#StorageProvider+updateHistory) @@ -86,16 +70,13 @@ Creates an instance of StorageProvider. | config | Object | | A configuration object. | | config.content_dir | string | | The directory to store documents. | | config.history_dir | string | | The directory to store document histories. | -| config.data_dir | string | | The directory to store objects. | | [config.extension] | string | "json" | The file extension to use for file, name of the employee. | -| [config.analytics_file] | string | "visits" | The name of the file to store page views. | | [config.spaces_document] | number | | The spaces parameter for JSON stringifying documents. | -| [config.spaces_data] | number | | The spaces parameter for JSON stringifying data. | | [config.spaces_history] | number | | The spaces parameter for JSON stringifying history. | **Example** *(Init StorageProvider)* ```js -const storageProvider = new StorageProvider({ content_dir: 'content', history_dir: 'history', data_dir: 'data', spaces_document: 2 }); +const storageProvider = new StorageProvider({ content_dir: 'content', history_dir: 'history', spaces_document: 2 }); ``` @@ -121,85 +102,17 @@ Returns all unique tags. storageProvider.tags(); ➜ ['first-tag', ...] ``` - + -### storageProvider.getTaggedDocuments(tag, [limit], fields) ⇒ Promise -Returns all documents matching a given tag. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| tag | string | | The tag to compare against other documents. | -| [limit] | number | 1000 | The maximum number of documents to return. | -| fields | Array.<string> | | Unused: the fields to return on the documents. | - - - -### storageProvider.getRelatedDocuments(document, limit, fields) ⇒ Promise -Returns a given number of documents related to a given document by comparing tags. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Description | -| --- | --- | --- | -| document | UttoriDocument | The document to compare against other documents. | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.getRecentDocuments(limit, fields) ⇒ Promise -Returns a given number of documents sorted by most recently updated. +### storageProvider.getQuery(query) ⇒ Promise +Returns all documents matching a given query. **Kind**: instance method of [StorageProvider](#StorageProvider) **Returns**: Promise - Promise object represents all matching documents. | Param | Type | Description | | --- | --- | --- | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.getPopularDocuments(limit, fields) ⇒ Promise -Returns a given number of documents sorted by most visited. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.getRandomDocuments(limit, fields) ⇒ Promise -Returns a given number of randomly selected documents. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.augmentDocuments(documents, _fields) ⇒ Promise -Ensures a given set of fields are presenton on a given set of documents. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all augmented documents. - -| Param | Type | Description | -| --- | --- | --- | -| documents | Array.<UttoriDocument> | The documents to ensure fields are set on. | -| _fields | Array.<string> | Unused: the fields to return on the documents. | +| query | string | The conditions on which documents should be returned. | @@ -285,127 +198,12 @@ Removes a document from the file system. | --- | --- | --- | | slug | string | The slug identifying the document. | - - -### storageProvider.storeObject(name, data) -Saves a JSON object to the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to be saved. | -| data | string \| Object | The JSON data for the file to be saved. | - - - -### storageProvider.updateObject(name, key, value) -Updates a value in a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to be updated. | -| key | string | The key of the value to be updated. | -| value | Array \| number \| string \| Object | The JSON data for the file to be saved. | - - - -### storageProvider.incrementObject(name, key, [amount]) -Increment a value by a given amount in a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| name | string | | The name of the file to be updated. | -| key | string | | The key of the value to be updated. | -| [amount] | number | 1 | The value to be added. | - - - -### storageProvider.decrementObject(name, key, [amount]) -Decrement a value by a given amount in a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| name | string | | The name of the file to be updated. | -| key | string | | The key of the value to be updated. | -| [amount] | number | 1 | The value to be subtracted. | - - - -### storageProvider.readObject(name, fallback) ⇒ Promise.<Object> -Reads a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise.<Object> - Promise object represents the returned object. - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to be read. | -| fallback | Object | The backup value to use if no value is found. | - - - -### storageProvider.readObjectValue(name, key, fallback) ⇒ Promise.<Object> -Reads a specific value from a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise.<Object> - Promise object represents the returned object. - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to get the value from. | -| key | string | The key of the value to be returned. | -| fallback | Object | The backup value to use if no value is found. | - ### storageProvider.refresh() Reloads all documents from the file system into the cache. **Kind**: instance method of [StorageProvider](#StorageProvider) - - -### storageProvider.deleteFile(folder, name) -Deletes a file from the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Description | -| --- | --- | --- | -| folder | string | The folder of the file to be deleted. | -| name | string | The name of the file to be deleted. | - - - -### storageProvider.readFile(folder, name) ⇒ Object -Reads a file from the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Object - - The parsed JSON file contents. - -| Param | Type | Description | -| --- | --- | --- | -| folder | string | The folder of the file to be read. | -| name | string | The name of the file to be read. | - - - -### storageProvider.readFolder(folder) ⇒ Array.<string> -Reads a folder from the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Array.<string> - - The file paths found in the folder. - -| Param | Type | Description | -| --- | --- | --- | -| folder | string | The folder to be read. | - ### storageProvider.updateHistory(slug, content, originalSlug) diff --git a/docs/README.md b/docs/README.md index f3c1fb7..c612b84 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,10 +20,8 @@ npm install --save uttori-storage-provider-json-file { content_dir: '', history_dir: '', - data_dir: '', extension: 'json', spaces_document: null, - spaces_data: null, spaces_history: null, } ``` @@ -50,12 +48,7 @@ Storage for Uttori documents using JSON files stored on the local file system. * [new StorageProvider(config)](#new_StorageProvider_new) * [.all()](#StorageProvider+all) ⇒ Promise * [.tags()](#StorageProvider+tags) ⇒ Promise - * [.getTaggedDocuments(tag, [limit], fields)](#StorageProvider+getTaggedDocuments) ⇒ Promise - * [.getRelatedDocuments(document, limit, fields)](#StorageProvider+getRelatedDocuments) ⇒ Promise - * [.getRecentDocuments(limit, fields)](#StorageProvider+getRecentDocuments) ⇒ Promise - * [.getPopularDocuments(limit, fields)](#StorageProvider+getPopularDocuments) ⇒ Promise - * [.getRandomDocuments(limit, fields)](#StorageProvider+getRandomDocuments) ⇒ Promise - * [.augmentDocuments(documents, _fields)](#StorageProvider+augmentDocuments) ⇒ Promise + * [.getQuery(query)](#StorageProvider+getQuery) ⇒ Promise * [.get(slug)](#StorageProvider+get) ⇒ Promise * [.getHistory(slug)](#StorageProvider+getHistory) ⇒ Promise * [.getRevision(slug, revision)](#StorageProvider+getRevision) ⇒ Promise @@ -63,16 +56,7 @@ Storage for Uttori documents using JSON files stored on the local file system. * [.updateValid(document, originalSlug)](#StorageProvider+updateValid) ℗ * [.update(document, originalSlug)](#StorageProvider+update) * [.delete(slug)](#StorageProvider+delete) - * [.storeObject(name, data)](#StorageProvider+storeObject) - * [.updateObject(name, key, value)](#StorageProvider+updateObject) - * [.incrementObject(name, key, [amount])](#StorageProvider+incrementObject) - * [.decrementObject(name, key, [amount])](#StorageProvider+decrementObject) - * [.readObject(name, fallback)](#StorageProvider+readObject) ⇒ Promise.<Object> - * [.readObjectValue(name, key, fallback)](#StorageProvider+readObjectValue) ⇒ Promise.<Object> * [.refresh()](#StorageProvider+refresh) - * [.deleteFile(folder, name)](#StorageProvider+deleteFile) - * [.readFile(folder, name)](#StorageProvider+readFile) ⇒ Object - * [.readFolder(folder)](#StorageProvider+readFolder) ⇒ Array.<string> * [.updateHistory(slug, content, originalSlug)](#StorageProvider+updateHistory) @@ -86,16 +70,13 @@ Creates an instance of StorageProvider. | config | Object | | A configuration object. | | config.content_dir | string | | The directory to store documents. | | config.history_dir | string | | The directory to store document histories. | -| config.data_dir | string | | The directory to store objects. | | [config.extension] | string | "json" | The file extension to use for file, name of the employee. | -| [config.analytics_file] | string | "visits" | The name of the file to store page views. | | [config.spaces_document] | number | | The spaces parameter for JSON stringifying documents. | -| [config.spaces_data] | number | | The spaces parameter for JSON stringifying data. | | [config.spaces_history] | number | | The spaces parameter for JSON stringifying history. | **Example** *(Init StorageProvider)* ```js -const storageProvider = new StorageProvider({ content_dir: 'content', history_dir: 'history', data_dir: 'data', spaces_document: 2 }); +const storageProvider = new StorageProvider({ content_dir: 'content', history_dir: 'history', spaces_document: 2 }); ``` @@ -121,85 +102,17 @@ Returns all unique tags. storageProvider.tags(); ➜ ['first-tag', ...] ``` - + -### storageProvider.getTaggedDocuments(tag, [limit], fields) ⇒ Promise -Returns all documents matching a given tag. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| tag | string | | The tag to compare against other documents. | -| [limit] | number | 1000 | The maximum number of documents to return. | -| fields | Array.<string> | | Unused: the fields to return on the documents. | - - - -### storageProvider.getRelatedDocuments(document, limit, fields) ⇒ Promise -Returns a given number of documents related to a given document by comparing tags. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Description | -| --- | --- | --- | -| document | UttoriDocument | The document to compare against other documents. | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.getRecentDocuments(limit, fields) ⇒ Promise -Returns a given number of documents sorted by most recently updated. +### storageProvider.getQuery(query) ⇒ Promise +Returns all documents matching a given query. **Kind**: instance method of [StorageProvider](#StorageProvider) **Returns**: Promise - Promise object represents all matching documents. | Param | Type | Description | | --- | --- | --- | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.getPopularDocuments(limit, fields) ⇒ Promise -Returns a given number of documents sorted by most visited. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.getRandomDocuments(limit, fields) ⇒ Promise -Returns a given number of randomly selected documents. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all matching documents. - -| Param | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of documents to return. | -| fields | Array.<string> | Unused: the fields to return on the documents. | - - - -### storageProvider.augmentDocuments(documents, _fields) ⇒ Promise -Ensures a given set of fields are presenton on a given set of documents. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise - Promise object represents all augmented documents. - -| Param | Type | Description | -| --- | --- | --- | -| documents | Array.<UttoriDocument> | The documents to ensure fields are set on. | -| _fields | Array.<string> | Unused: the fields to return on the documents. | +| query | string | The conditions on which documents should be returned. | @@ -285,127 +198,12 @@ Removes a document from the file system. | --- | --- | --- | | slug | string | The slug identifying the document. | - - -### storageProvider.storeObject(name, data) -Saves a JSON object to the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to be saved. | -| data | string \| Object | The JSON data for the file to be saved. | - - - -### storageProvider.updateObject(name, key, value) -Updates a value in a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to be updated. | -| key | string | The key of the value to be updated. | -| value | Array \| number \| string \| Object | The JSON data for the file to be saved. | - - - -### storageProvider.incrementObject(name, key, [amount]) -Increment a value by a given amount in a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| name | string | | The name of the file to be updated. | -| key | string | | The key of the value to be updated. | -| [amount] | number | 1 | The value to be added. | - - - -### storageProvider.decrementObject(name, key, [amount]) -Decrement a value by a given amount in a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| name | string | | The name of the file to be updated. | -| key | string | | The key of the value to be updated. | -| [amount] | number | 1 | The value to be subtracted. | - - - -### storageProvider.readObject(name, fallback) ⇒ Promise.<Object> -Reads a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise.<Object> - Promise object represents the returned object. - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to be read. | -| fallback | Object | The backup value to use if no value is found. | - - - -### storageProvider.readObjectValue(name, key, fallback) ⇒ Promise.<Object> -Reads a specific value from a JSON object on the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Promise.<Object> - Promise object represents the returned object. - -| Param | Type | Description | -| --- | --- | --- | -| name | string | The name of the file to get the value from. | -| key | string | The key of the value to be returned. | -| fallback | Object | The backup value to use if no value is found. | - ### storageProvider.refresh() Reloads all documents from the file system into the cache. **Kind**: instance method of [StorageProvider](#StorageProvider) - - -### storageProvider.deleteFile(folder, name) -Deletes a file from the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) - -| Param | Type | Description | -| --- | --- | --- | -| folder | string | The folder of the file to be deleted. | -| name | string | The name of the file to be deleted. | - - - -### storageProvider.readFile(folder, name) ⇒ Object -Reads a file from the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Object - - The parsed JSON file contents. - -| Param | Type | Description | -| --- | --- | --- | -| folder | string | The folder of the file to be read. | -| name | string | The name of the file to be read. | - - - -### storageProvider.readFolder(folder) ⇒ Array.<string> -Reads a folder from the file system. - -**Kind**: instance method of [StorageProvider](#StorageProvider) -**Returns**: Array.<string> - - The file paths found in the folder. - -| Param | Type | Description | -| --- | --- | --- | -| folder | string | The folder to be read. | - ### storageProvider.updateHistory(slug, content, originalSlug)