Utils

Provides convenient methods for managing documents in the local database.

search(keyword, options)

Search for notes

Retrieves notes which match given keyword.

Parameters

Name
keyword
Type
string
Required
Description
The search keyword. The syntax is described here.
Name
options
Type
object
Description
Options include sorting, limiting, and skipping notes.
- Name
  sort
  Type
  object[]
  Description
  An array of objects, each indicating a field and order. Supported fields are: 'rank', 'title', 'updatedAt', 'createdAt' and 'tagCount'. See notes.all for 'tagCount'. 'rank' sorts by relevance, best first when ascending. It requires the keyword to contain words to match, and throws an error if the keyword consists only of qualifiers such as book: or tag:. Example: [ { rank: 'asc' } ], [ { updatedAt: 'asc' } ]. Default: [ { rank: 'asc' } ] if the keyword contains words to match, otherwise [ { updatedAt: 'desc' } ].
- Name
  pinnedFirst
  Type
  boolean
  Description
  Whether to list pinned notes first. It has no effect when sorting by 'rank'. Default is true.
- Name
  limit
  Type
  number | false
  Description
  Number of notes to fetch. Pass false to fetch all matching notes. Default is 50.
- Name
  skip
  Type
  number
  Description
  Number of notes to skip. Default is 0.
- Name
  includeDocs
  Type
  boolean
  Description
  Whether the result rows include the note documents. When false, each row contains only the note's id and rev. Default is true.
- Name
  highlightMatches
  Type
  boolean
  Description
  Whether to return where the keyword matched in each note's title and body. Default is true when options is omitted, and false otherwise.

Returns a query result with matching notes. The notes are in rows, each as rows[].doc. With highlightMatches, each row also has extra.fts, which contains titleHighlights and bodyHighlights. Each highlight has offStart and offEnd, the offsets in the whole text, and line, chStart and chEnd, the position within its line.

Request

const db = env.localDB
const results = await db.utils.search('foobar', {
  sort: [ { updatedAt: 'asc' } ],
  limit: 20,
  highlightMatches: true
})

Response

{
  "query": {
    "sort": [ { "updatedAt": "asc" } ],
    "limit": 20,
    "highlightMatches": true,
    "index": "fts",
    "conditions": [
      {
        "type": "keyword",
        "term": "foobar",
        "phrase": false,
        "exclude": false
      }
    ]
  },
  "totalRows": Infinity,
  "cursor": {
    "sort": [ { "updatedAt": "asc" } ],
    "limit": 20,
    "skip": 20,
    "highlightMatches": true,
    "index": "fts",
    "conditions": [
      {
        "type": "keyword",
        "term": "foobar",
        "phrase": false,
        "exclude": false
      }
    ]
  },
  "includeDocs": true,
  "rows": [
    {
      "doc": {
        "doctype": "markdown",
        "updatedAt": 1461564004766,
        "createdAt": 1461563995746,
        "bookId": "book:32b385767dc2",
        "status": "none",
        "numOfTasks": 0,
        "numOfCheckedTasks": 0,
        "title": "foobar",
        "body": "body...",
        "_id": "note:4eeb997c",
        "_rev": "8-d18201be3336c70979c6a375b497b3a7"
      },
      "extra": {
        "fts": {
          "titleHighlights": [
            { "offStart": 0, "offEnd": 6, "line": 0, "chStart": 0, "chEnd": 6 }
          ],
          "bodyHighlights": []
        }
      }
    },
    ...
  ]
}

deleteTag(tagId)

Delete a tag

Delete a tag with the specified ID and remove it from associated notes.

Parameters

Name
tagId
Type
string
Required
Description
The tag ID to delete.

Returns

A Promise that will reject if the tag cannot be deleted.

Request

const db = env.localDB
await db.utils.deleteTag('tag:tBELDUITs')

moveNoteToBook(noteId, moveToBookId)

Move a note to a notebook

Move a note to a designated notebook.

Parameters

Name
noteId
Type
string
Required
Description
The note ID you wish to move.
Name
moveToBookId
Type
string
Required
Description
The destination notebook ID where the note will be moved to.

Returns

Returns a Promise. Rejects if there's a failure in moving the note.

Request

const db = env.localDB
await db.utils.moveNoteToBook('note:BKzzd8iGK', 'book:4eeb997c')

moveNoteToBookBatch(noteIds, moveToBookId)

Move multiple notes to a notebook

Move a batch of notes to a designated notebook.

Parameters

Name
noteIds
Type
array
Required
Description
An array of note IDs you wish to move.
Name
moveToBookId
Type
string
Required
Description
The destination notebook ID where the notes will be moved to.

Returns

Returns a Promise. Rejects if there's a failure in moving the notes.

Request

const db = env.localDB
await db.utils.moveNoteToBookBatch(["note:BKzzd8iGK", "note:8eea9f7c"], 'book:4eeb997c')

duplicateNote(noteId)

Duplicate a note

Duplicate a note with the provided note ID. The duplicated note will have newly assigned values for _id, createdAt, updatedAt, and _rev.

Parameters

Name
noteId
Type
string
Required
Description
The ID of the note you wish to duplicate.

Returns

Returns a Promise which will resolve with the duplicated note details.

Request

const db = env.localDB
await db.utils.duplicateNote("note:BKzzd8iGK")

duplicateNoteBatch(noteIds)

Duplicate multiple notes

Duplicate a batch of notes. Each duplicated note will have newly assigned values for _id, createdAt, updatedAt, and _rev.

Parameters

Name
noteIds
Type
array
Required
Description
An array of note IDs you wish to duplicate.

Returns

Returns a Promise which will resolve with the details of the duplicated notes.

Request

const db = env.localDB
await db.utils.duplicateNoteBatch(["note:BKzzd8iGK", "note:8eea9f7c"])

moveNotesToTrashOrDelete(noteIds)

Trash or delete multiple notes

Move the given notes to trash or if they are already in the trash, delete them permanently.

Parameters

Name
noteIds
Type
array
Required
Description
An array of note IDs to either move to trash or delete permanently.

Returns

Returns a Promise. Rejects if it fails to perform any of the operations.

Request

const db = env.localDB
await db.utils.moveNotesToTrashOrDelete(["note:BKzzd8iGK", "note:8eea9f7c"])

emptyTrash()

Empty Trash

Delete notes in trash permanently.

Returns

Returns a Promise which rejects if failed to empty trash.

Request

const db = env.localDB
await db.utils.emptyTrash()

setTagsBatch(noteIds, tags)

Set Tags Batch

Sets given tags to notes with specified IDs.

Parameters

Name
noteIds
Type
array
Required
Description
A list of IDs of notes to be set.
Name
tags
Type
array of string
Required
Description
A list of tag IDs to set.

Returns

Returns an Array of updated Notes.

Request

const db = env.localDB
await db.utils.setTagsBatch(["note:BKzzd8iGK", "note:8eea9f7c"], ["tag:tBELDUITs"])

setStatusBatch(noteIds, status)

Set Status Batch

Sets specified note status to notes with given IDs.

Parameters

Name
noteIds
Type
array
Required
Description
A list of IDs of notes to be set.
Name
status
Type
string
Required
Description
A note status which can be 'none', 'active', 'onHold', 'completed' or 'dropped'.

Request

const db = env.localDB
await db.utils.setStatusBatch(["note:BKzzd8iGK", "note:8eea9f7c"], "completed")

moveBook(bookId, newParentBookId)

Move a notebook

Sets a notebook with specified ID as a child of a notebook.

Parameters

Name
bookId
Type
string
Required
Description
A notebook ID to move.
Name
newParentBookId
Type
string or null
Description
A notebook ID of new parent notebook. Specifying null moves the notebook to the root.

Returns

Returns the updated Book.

Request

const db = env.localDB
await db.utils.moveBook("book:tjnPbJakw", "book:Bk5Ivk0T")

deleteBook(bookId)

Delete a notebook

Deletes a notebook with given ID and moves notes associated with it into trash.

Parameters

Name
bookId
Type
string
Required
Description
A notebook ID to delete.

Returns

Returns a Promise.

Request

const db = env.localDB
await db.utils.deleteBook("book:tjnPbJakw")

getBufferFromFile(fileId)

Get Buffer From File

Loads an image file as Buffer.

Parameters

Name
fileId
Type
string
Required
Description
A file ID to load.

Returns

Returns a content of the image file.

Request

const db = env.localDB
await db.utils.getBufferFromFile("file:5c2c2b2c")