Developers

Notes

Markdown

As the name suggests, notes are a core part of Inkdrop — A note contains an individual note data.

The note model

The note model contains all the information about your notes, such as their title, content written in Markdown format, associated notebook and tags, creation and modification timestamps, and any other metadata.

Properties

  • Name
    _id
    Type
    string
    Description

    The unique document ID which should start with note: and the remains are randomly generated string.

  • Name
    _rev
    Type
    string
    Description

    This is a CouchDB specific field. The current MVCC-token/revision of this document (mandatory and immutable).

  • Name
    body
    Type
    string
    Description

    The content of the note represented with Markdown.

  • Name
    bookId
    Type
    string
    Description

    The associated notebook ID.

  • Name
    createdAt
    Type
    number
    Description

    The date time when the note was created, represented with Unix timestamps in milliseconds.

  • Name
    doctype
    Type
    string
    Description

    The format type of the body field. It currently can take markdown only, reserved for the future.

  • Name
    migratedBy
    Type
    string
    Description

    The type of the data migration.

  • Name
    numOfCheckedTasks
    Type
    number
    Description

    The number of checked tasks, extracted from body.

  • Name
    numOfTasks
    Type
    number
    Description

    The number of tasks, extracted from body.

  • Name
    pinned
    Type
    boolean
    Description

    Whether the note is pinned to top.

  • Name
    share
    Type
    string
    Description

    The sharing mode of the note. One of: "private" or "public"

  • Name
    status
    Type
    string
    Description

    The status of the note. One of: "none" or "active" or "onHold" or "completed" or "dropped"

  • Name
    tags
    Type
    string[]
    Description

    The list of tag IDs.

  • Name
    title
    Type
    string
    Description

    The note title.

  • Name
    updatedAt
    Type
    number
    Description

    The date time when the note was last updated, represented with Unix timestamps in milliseconds.

The note object

{
  "_id": "note:BkgOZZUJzf",
  "_rev": "38-636e505958d24f9c21614d95ea03b5a1",
  "title": "Hello, world",
  "doctype": "markdown",
  "updatedAt": 1513330812556,
  "createdAt": 1513214207639,
  "tags": [
    "tag:a28ca207"
  ],
  "status": "none",
  "share": "private",
  "body": "markdown note body",
  "bookId": "book:first",
  "numOfTasks": 0,
  "numOfCheckedTasks": 0,
  "pinned": false
}

The note class

The Note class is a wrapper class that provides methods and functionalities related to handling notes.

Methods

  • Name
    static async loadWithId(noteId: string)
    Type
    Description

    A static asynchronous method that retrieves a note from the database using a specified note ID and returns an instance of the Note class initialized with that note.

  • Name
    constructor(initialValues: Partial<Note> = {})
    Type
    Description

    Constructs a new instance of the Note class. It sets the initial values of the note object based on the provided initialValues or uses default values.

  • Name
    getUpdatedAt()
    Type
    Description

    Returns the updatedAt property of the note as a JavaScript Date object.

  • Name
    getCreatedAt()
    Type
    Description

    Returns the createdAt property of the note as a JavaScript Date object.

  • Name
    isNoteShared()
    Type
    Description

    Determines if the note is shared. Returns true if the note is not private; otherwise, it returns false.

  • Name
    validate()
    Type
    Description

    Validates the note's properties using the validateNote function. Returns a list of validation errors or an empty list if the note is valid.

  • Name
    async save()
    Type
    Description

    An asynchronous method that first validates the note, then ensures the related notebook and tags exist. If all validations pass, it saves the note to the database.

  • Name
    toObject()
    Type
    Description

    Converts the Note instance into a plain JavaScript object of type Note.

  • Name
    toJson()
    Type
    Description

    Serializes the Note instance into a JSON string representation.

Import the class

const { Note } = require('inkdrop').models

Load a note from the database

const note = await Note.loadWithId('note:BKzzd8iGK')

Change its title

note.title = 'New title'

Save the change

await note.save()

Create a new note

const note = new Note({
  title: 'Hello',
  body: 'World'
})

Convert into a plain object

const object = note.toObject()

Convert into JSON

const json = note.toJson()
get(docId, options)

Retrieve a note

Retrieve a note with the given ID. You can also pass an array of note IDs to retrieve several notes at once.

Parameters

  • Name
    docId
    Type
    string | string[]
    Required
    Description

    The note ID, or an array of note IDs

  • Name
    options
    Type
    object
    Description

    Options. See PouchDB's documentation for available options. Ignored when docId is an array.

Returns

Returns a note if a valid note ID was provided. When given an array, returns an array of notes in the same order as the IDs. IDs of notes that do not exist are omitted instead of throwing an error, but an invalid note ID still throws.

Request

const db = env.localDB
const note = await db.notes.get('note:BKzzd8iGK')

Response

{
  "doctype": "markdown",
  "bookId": "book:tjnPbJakw",
  "createdAt": 1589165355584,
  "updatedAt": 1592532006000,
  "status": "active",
  "share": "private",
  "numOfTasks": 0,
  "numOfCheckedTasks": 0,
  "pinned": true,
  "title": "hello",
  "body": "example note",
  "tags": ["tag:HyBgJ94gx", "tag:h11OMPbSs"],
  "_id": "note:BKzzd8iGK",
  "_rev": "19-d882f96ee27f7b9f71f6183b0cab9193"
}
all(options)

List all notes

Retrieve a list of your notes.

Parameters

  • Name
    options
    Type
    object
    Description

    Object with the following keys:

    • Name
      sort
      Type
      object[]
      Description

      An array of objects, each indicating a field and order. Supported fields are: 'title', 'updatedAt', 'createdAt' and 'tagCount'. 'tagCount' ranks a note by how many of the listed notes share each of its tags, so notes with commonly used tags come first. For example: [ { updatedAt: 'asc' } ], [ { title: 'desc' } ]. Default: [ { updatedAt: 'desc' } ]

    • Name
      pinnedFirst
      Type
      boolean
      Description

      Whether to list pinned notes first. Default: true

    • Name
      limit
      Type
      number | false
      Description

      A number to limit how many notes to fetch. Pass false to fetch all notes. Default: 50

    • Name
      skip
      Type
      number
      Description

      A number of notes to skip at the start of a collection. Default: 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: true

Returns

Returns a query result. The notes are in rows, each as rows[].doc. cursor is the query for the next page, or null if there are no more notes.

Request

const db = env.localDB
const list = await db.notes.all({ limit: 20 })

Response

{
  query: {
    index: 'notes',
    limit: 20
  },
  totalRows: 9357,
  cursor: {
    index: 'notes',
    limit: 20,
    skip: 20
  },
  includeDocs: true,
  rows: [
    {
      doc: {
        doctype: 'markdown',
        updatedAt: 1461564004766,
        createdAt: 1461563995746,
        bookId: 'book:32b385767dc2',
        status: 'none',
        numOfTasks: 0,
        numOfCheckedTasks: 0,
        title: 'title...',
        body: 'body...',
        _id: 'note:4eeb997c',
        _rev: '8-d18201be3336c70979c6a375b497b3a7'
      }
    },
    ...
  ]
}
createId(): string

Create a note ID

Creates new note ID which is String

Parameters

No parameters

Returns

Returns a new note ID.

Request

const db = env.localDB
const noteId = await db.notes.createId()

Response

"note:8eea9f7c"
validateDocId(): boolean

Validate a note ID

Tests if the given docId is a valid note ID

Parameters

  • Name
    docId
    Type
    string
    Required
    Description

    A document ID to validate

Returns

Returns true if valid

Request

const db = env.localDB
const isValid = await db.notes.validateDocId('note:8eea9f7c')

Response

true
put(doc)

Create or update a note

Create a new note or update an existing note. If the note already exists, you must specify its revision _rev, otherwise a conflict will occur.

Parameters

  • Name
    doc
    Type
    object
    Required
    Description

    A Note data to store

Returns

It throws an InvalidDataError if the given doc was invalid. The response contains the id of the document, the new rev, and an ok to reassure you that everything is okay.

Request

const db = env.localDB
const result = await db.notes.put({
  "_id": "note:BKzzd8iGK",
  "doctype": "markdown",
  "bookId": "book:tjnPbJakw",
  "createdAt": 1589165355584,
  "updatedAt": 1592532006000,
  "status": "active",
  "share": "private",
  "numOfTasks": 0,
  "numOfCheckedTasks": 0,
  "pinned": true,
  "title": "hello",
  "body": "example note",
  "tags": ["tag:HyBgJ94gx", "tag:h11OMPbSs"]
})

Response

{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "1-a6157a5ea545c99b00ff904eef05fd9f"
}
remove(docId)

Remove a note

Deletes a note with the given note ID.

Parameters

  • Name
    docId
    Type
    string
    Required
    Description

    A note ID to delete.

Returns

The response contains the id of the document, the new rev, and an ok to reassure you that everything is okay.

Request

const db = env.localDB
const result = await db.notes.remove("note:BKzzd8iGK")

Response

{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "2-9af304be281790604d1d8a4b0f4c9adb"
}
removeBatch(docIds)

Remove a batch of notes

Deletes multiple notes with the given note IDs.

Parameters

  • Name
    docIds
    Type
    string[]
    Required
    Description

    An Array of note IDs to delete.

Returns

Returns an array of new revision IDs.

Request

const db = env.localDB
const result = await db.notes.removeBatch(["note:BKzzd8iGK", "note:8eea9f7c"])

Response

[
  {
    "ok": true,
    "id": "note:BKzzd8iGK",
    "rev": "2-9af304be281790604d1d8a4b0f4c9adb"
  },
  {
    "ok": true,
    "id": "note:8eea9f7c",
    "rev": "3-faf004b42827906a4dadbabb0fbc9aff"
  }
]
countAll()

Count number of notes

Counts a number of notes in the database.

Parameters

No parameters.

Returns

Returns a number of notes stored in the database.

Request

const db = env.localDB
const num = await db.notes.countAll()

Response

21
findInBook(bookId, options)

List notes within a specific notebook

Retrieves notes associated with given notebook ID.

Parameters

  • Name
    bookId
    Type
    string
    Required
    Description

    A notebook ID to find.

  • Name
    options
    Type
    object
    Description

    List options. See :all for details.

Returns

Returns a query result.

Request

const db = env.localDB
const num = await db.notes.findInBook('book:tjnPbJakw')

Response

{
  query: {
    index: 'notes',
    bookId: 'book:tjnPbJakw'
  },
  totalRows: 9357,
  cursor: {
    index: 'notes',
    bookId: 'book:tjnPbJakw',
    limit: 50,
    skip: 50
  },
  includeDocs: true,
  rows: [
    {
      doc: {
        doctype: 'markdown',
        updatedAt: 1461564004766,
        createdAt: 1461563995746,
        bookId: 'book:tjnPbJakw',
        status: 'none',
        numOfTasks: 0,
        numOfCheckedTasks: 0,
        title: 'title...',
        body: 'body...',
        _id: 'note:4eeb997c',
        _rev: '8-d18201be3336c70979c6a375b497b3a7'
      }
    },
    ...
  ]
}
findWithTag(tagId, options)

List notes with a specific tag

Retrieves notes associated with the given tag ID.

Parameters

  • Name
    tagId
    Type
    string
    Required
    Description

    A tag ID to find.

  • Name
    options
    Type
    object
    Description

    List options. See :all for details.

Returns

Returns a query result.

Request

const db = env.localDB
const num = await db.notes.findWithTag('tag:4eeb997c')

Response

{
  query: {
    index: 'notes',
    tagId: 'tag:4eeb997c'
  },
  totalRows: 9357,
  cursor: {
    index: 'notes',
    tagId: 'tag:4eeb997c',
    limit: 50,
    skip: 50
  },
  includeDocs: true,
  rows: [
    {
      doc: {
        doctype: 'markdown',
        updatedAt: 1461564004766,
        createdAt: 1461563995746,
        bookId: 'book:tjnPbJakw',
        status: 'none',
        numOfTasks: 0,
        numOfCheckedTasks: 0,
        title: 'title...',
        body: 'body...',
        _id: 'note:4eeb997c',
        _rev: '8-d18201be3336c70979c6a375b497b3a7'
      }
    },
    ...
  ]
}
findWithStatus(statue, options)

List notes with a specific status

Retrieves notes with the given note status.

Parameters

  • Name
    status
    Type
    string
    Required
    Description

    A note status, which can be 'none', 'active', 'onHold', 'completed' or 'dropped'.

  • Name
    options
    Type
    object
    Description

    List options. See :all for details.

Returns

Returns a query result.

Request

const db = env.localDB
const num = await db.notes.findWithStatus('active')

Response

{
  query: {
    index: 'notes',
    status: 'active'
  },
  totalRows: 9357,
  cursor: {
    index: 'notes',
    status: 'active',
    limit: 50,
    skip: 50
  },
  includeDocs: true,
  rows: [
    {
      doc: {
        doctype: 'markdown',
        updatedAt: 1461564004766,
        createdAt: 1461563995746,
        bookId: 'book:tjnPbJakw',
        status: 'active',
        numOfTasks: 0,
        numOfCheckedTasks: 0,
        title: 'title...',
        body: 'body...',
        _id: 'note:4eeb997c',
        _rev: '8-d18201be3336c70979c6a375b497b3a7'
      }
    },
    ...
  ]
}
count(query)

Count notes matching filters

Counts the notes that a list with the same filters would contain. Like the list methods, it excludes notes in the trash and notes whose status is 'completed' or 'dropped' unless the filters specify them.

Parameters

  • Name
    query
    Type
    object
    Description

    Object with the following keys:

    • Name
      bookId
      Type
      string | string[]
      Description

      A notebook ID, or an array of notebook IDs.

    • Name
      tagId
      Type
      string
      Description

      A tag ID.

    • Name
      status
      Type
      string | string[]
      Description

      A note status, or an array of note statuses.

Returns

Returns the number of matching notes.

Request

const db = env.localDB
const num = await db.notes.count({ tagId: 'tag:4eeb997c' })

Response

12
findAllIdsInBook(bookId, options)

List all note IDs in a notebook

Retrieves the IDs of every note in the given notebook, including notes whose status is 'completed' or 'dropped'.

Parameters

  • Name
    bookId
    Type
    string
    Required
    Description

    A notebook ID to find.

  • Name
    options
    Type
    object
    Description

    Object with the following keys:

    • Name
      includeChildren
      Type
      boolean
      Description

      Whether to include notes in the descendant notebooks.

    • Name
      tagId
      Type
      string
      Description

      A tag ID to narrow the notes down to.

Returns

Returns an array of note IDs.

Request

const db = env.localDB
const noteIds = await db.notes.findAllIdsInBook('book:tjnPbJakw', {
  includeChildren: true
})

Response

["note:4eeb997c", "note:BKzzd8iGK"]
findAllIdsWithTag(tagId)

List all note IDs with a tag

Retrieves the IDs of every note with the given tag, including notes in the trash, templates, and notes whose status is 'completed' or 'dropped'.

Parameters

  • Name
    tagId
    Type
    string
    Required
    Description

    A tag ID to find.

Returns

Returns an array of note IDs.

Request

const db = env.localDB
const noteIds = await db.notes.findAllIdsWithTag('tag:4eeb997c')

Response

["note:4eeb997c", "note:BKzzd8iGK"]
Can you help us improve the docs? 🙏

The source of these docs is here on GitHub. If you see a way these docs can be improved, please fork us!