Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(swing-store-simple): update JSDoc to fix warnings #2399

Merged
merged 1 commit into from
Feb 11, 2021
Merged

chore(swing-store-simple): update JSDoc to fix warnings #2399

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 27 additions & 23 deletions packages/swing-store-simple/simpleSwingStore.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@ import fs from 'fs';
import path from 'path';
import Readlines from 'n-readlines';

/**
* @typedef {ReturnType<typeof makeStorageInMemory>['storage']} SwingStore
*/

function safeUnlink(filePath) {
try {
fs.unlinkSync(filePath);
Expand All @@ -19,7 +23,7 @@ function safeUnlink(filePath) {
* that work on string keys and accept string values. A lot of kernel-side
* code expects to get an object that implements the Storage API.
*
* @returns an object: {
* returns an object: {
* storage, // the storage API object itself
* state // the underlying map that holds the state in memory
* }
Expand All @@ -30,9 +34,9 @@ function makeStorageInMemory() {
/**
* Test if the state contains a value for a given key.
*
* @param key The key that is of interest.
* @param {string} key The key that is of interest.
*
* @returns true if a value is stored for the key, false if not.
* @returns {boolean} true if a value is stored for the key, false if not.
*
* @throws if key is not a string.
*/
Expand All @@ -50,9 +54,9 @@ function makeStorageInMemory() {
* Note that this can be slow as it's only intended for use in debugging and
* test result verification.
*
* @param start Start of the key range of interest (inclusive). An empty
* @param {string} start Start of the key range of interest (inclusive). An empty
* string indicates a range from the beginning of the key set.
* @param end End of the key range of interest (exclusive). An empty string
* @param {string} end End of the key range of interest (exclusive). An empty string
* indicates a range through the end of the key set.
*
* @yields an iterator for the keys from start <= key < end
Expand All @@ -78,9 +82,9 @@ function makeStorageInMemory() {
/**
* Obtain the value stored for a given key.
*
* @param key The key whose value is sought.
* @param {string} key The key whose value is sought.
*
* @returns the (string) value for the given key, or undefined if there is no
* @returns {string|undefined} the (string) value for the given key, or undefined if there is no
* such value.
*
* @throws if key is not a string.
Expand All @@ -96,8 +100,8 @@ function makeStorageInMemory() {
* Store a value for a given key. The value will replace any prior value if
* there was one.
*
* @param key The key whose value is being set.
* @param value The value to set the key to.
* @param {string} key The key whose value is being set.
* @param {string} value The value to set the key to.
*
* @throws if either parameter is not a string.
*/
Expand All @@ -115,7 +119,7 @@ function makeStorageInMemory() {
* Remove any stored value for a given key. It is permissible for there to
* be no existing stored value for the key.
*
* @param key The key whose value is to be deleted
* @param {string} key The key whose value is to be deleted
*
* @throws if key is not a string.
*/
Expand All @@ -140,11 +144,11 @@ function makeStorageInMemory() {
/**
* Do the work of `initSwingStore` and `openSwingStore`.
*
* @param dirPath Path to a directory in which database files may be kept, or
* @param {string} dirPath Path to a directory in which database files may be kept, or
* null.
* @param forceReset If true, initialize the database to an empty state
* @param {boolean} [forceReset] If true, initialize the database to an empty state
*
* @returns an object: {
* returns an object: {
* storage, // a storage API object to load and store data
* commit, // a function to commit changes made since the last commit
* close // a function to shutdown the store, abandoning any uncommitted
Expand Down Expand Up @@ -216,13 +220,13 @@ function makeSwingStore(dirPath, forceReset = false) {
* serialized to a text file. If there is an existing store at the given
* `dirPath`, it will be reinitialized to an empty state.
*
* @param dirPath Path to a directory in which database files may be kept.
* @param {string} dirPath Path to a directory in which database files may be kept.
* This directory need not actually exist yet (if it doesn't it will be
* created) but it is reserved (by the caller) for the exclusive use of this
* swing store instance. If this is nullish, the swing store created will
* have no backing store and thus be non-persistent.
*
* @returns an object: {
* returns an object: {
* storage, // a storage API object to load and store data
* commit, // a function to commit changes made since the last commit
* close // a function to shutdown the store, abandoning any uncommitted
Expand All @@ -241,12 +245,12 @@ export function initSwingStore(dirPath) {
* a text file. If there is no existing store at the given `dirPath`, a new,
* empty store will be created.
*
* @param dirPath Path to a directory in which database files may be kept.
* @param {string} dirPath Path to a directory in which database files may be kept.
* This directory need not actually exist yet (if it doesn't it will be
* created) but it is reserved (by the caller) for the exclusive use of this
* swing store instance.
*
* @returns an object: {
* returns an object: {
* storage, // a storage API object to load and store data
* commit, // a function to commit changes made since the last commit
* close // a function to shutdown the store, abandoning any uncommitted
Expand All @@ -268,9 +272,9 @@ export function openSwingStore(dirPath) {
* stupidest possible way, hence it is likely to be a performance and memory
* hog if you attempt to use it on anything real.
*
* @param storage The swing storage whose state is to be extracted.
* @param {SwingStore} storage The swing storage whose state is to be extracted.
*
* @returns an array representing all the current state in `storage`, one
* @returns {Array<[string, string]>} an array representing all the current state in `storage`, one
* element of the form [key, value] per key/value pair.
*/
export function getAllState(storage) {
Expand All @@ -288,8 +292,8 @@ export function getAllState(storage) {
* general store initialization mechanism. In particular, note that it does
* not bother to remove any existing state in the store that it is given.
*
* @param storage The swing storage whose state is to be set.
* @param stuff An array of key/value pairs, each element of the form [key, value]
* @param {SwingStore} storage The swing storage whose state is to be set.
* @param {Array<[string, string]>} stuff An array of key/value pairs, each element of the form [key, value]
*/
export function setAllState(storage, stuff) {
for (const k of Object.getOwnPropertyNames(stuff)) {
Expand All @@ -300,10 +304,10 @@ export function setAllState(storage, stuff) {
/**
* Is this directory a compatible swing store?
*
* @param dirPath Path to a directory in which database files might be present.
* @param {string} dirPath Path to a directory in which database files might be present.
* This directory need not actually exist
*
* @returns boolean
* @returns {boolean}
* If the directory is present and contains the files created by initSwingStore
* or openSwingStore, returns true. Else returns false.
*
Expand Down