Developers

Notes

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.

Parameters

  • Name
    docId
    Type
    string
    Required
    Description

    The note ID

  • Name
    options
    Type
    object
    Description

    Options. See PouchDB's documentation for available options.

Returns

Returns a note if a valid note ID was provided.

Request

const db = inkdrop.main.dataStore.getLocalDB()
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
      string
      Description

      An array of an object indicating the field and order. Inkdrop supports sorting notes with only one field. Supported fields are: 'title', 'updatedAt' and 'createdAt'. For example: [ { updatedAt: 'asc' } ], [ { title: 'desc' } ].

    • Name
      limit
      Type
      number
      Description

      A number to limit how many notes to fetch. Default: 20

    • 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 return values include doc contents. Default: true

Returns

Returns a list of notes.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const list = await db.notes.all({ limit: 20 })

Response

{
  query: {
    index: 'index_notes',
    startkey: ['n', 'u', 0, 0],
    endkey: ['n', 'u', {}, {}],
    descending: false,
    limit: 20
  },
  totalRows: 9357,
  cursor: {
    index: 'index_notes',
    startkey: ['n', 'u', 0, 0],
    endkey: ['n', 'u', {}, {}],
    descending: false,
    limit: 20,
    skip: 20
  },
  includeDocs: true,
  docs: [
    {
      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 = inkdrop.main.dataStore.getLocalDB()
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 = inkdrop.main.dataStore.getLocalDB()
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 = inkdrop.main.dataStore.getLocalDB()
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 = inkdrop.main.dataStore.getLocalDB()
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 = inkdrop.main.dataStore.getLocalDB()
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 = inkdrop.main.dataStore.getLocalDB()
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 = inkdrop.main.dataStore.getLocalDB()
const num = await db.notes.findInBook('book:tjnPbJakw')

Response

{
  query: {
    index: 'index_notes',
    startkey: [ 'b', 'u', 'book:tjnPbJakw', 1, 0, 0 ],
    endkey: [ 'b', 'u', 'book:tjnPbJakw', 2, {}, {} ]
    descending: false,
    limit: 20
  },
  totalRows: 9357,
  cursor: {
    index: 'index_notes',
    startkey: [ 'b', 'u', 'book:tjnPbJakw', 1, 0, 0 ],
    endkey: [ 'b', 'u', 'book:tjnPbJakw', 2, {}, {} ]
    descending: false,
    limit: 20,
    skip: 20
  },
  includeDocs: true,
  docs: [
    {
      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 = inkdrop.main.dataStore.getLocalDB()
const num = await db.notes.findWithTag('tag:4eeb997c')

Response

{
  query: {
    index: 'index_notes',
    startkey: [ 't', 'u', 'tag:4eeb997c', 1, 0, 0 ],
    endkey: [ 't', 'u', 'tag:4eeb997c', 2, {}, {} ]
    descending: false,
    limit: 20
  },
  totalRows: 9357,
  cursor: {
    index: 'index_notes',
    startkey: [ 't', 'u', 'tag:4eeb997c', 1, 0, 0 ],
    endkey: [ 't', 'u', 'tag:4eeb997c', 2, {}, {} ]
    descending: false,
    limit: 20,
    skip: 20
  },
  includeDocs: true,
  docs: [
    {
      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 = inkdrop.main.dataStore.getLocalDB()
const num = await db.notes.findWithStatus('active')

Response

{
  query: {
    index: 'index_notes',
    startkey: [ 's', 'u', 'active', 1, 0, 0 ],
    endkey: [ 's', 'u', 'active', 2, {}, {} ]
    descending: false,
    limit: 20
  },
  totalRows: 9357,
  cursor: {
    index: 'index_notes',
    startkey: [ 's', 'u', 'active', 1, 0, 0 ],
    endkey: [ 's', 'u', 'active', 2, {}, {} ]
    descending: false,
    limit: 20,
    skip: 20
  },
  includeDocs: true,
  docs: [
    {
      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'
    },
    ...
  ]
}
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!