Files

Files in Inkdrop are primarily used as image attachments that can be inserted into notes.

The file model

Files capture all the essential details about the image attachments, such as content type, data, associated note IDs, and other crucial metadata.

Properties

Name
_id
Type
string
Description
The unique document ID which should start with file: 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
contentLength
Type
number
Description
The content length of the file, with a value <= 10485760.
Name
contentType
Type
string
Description
The MIME type of the content. One of: "image/png", "image/jpeg", "image/jpg", "image/svg+xml", "image/gif", "image/heic", or "image/heif". Length is between 0 and 128 characters.
Name
createdAt
Type
number
Description
The date time when the note was created, represented with Unix timestamps in milliseconds.
Name
name
Type
string
Description
The file name, with a length between 1 and 128 characters.
Name
publicIn
Type
array
Description
An array of the note IDs where the file is included.
Name
_attachments.index
Type
object
Description
The attachment object with the following keys:
- Name
  content_type
  Type
  string
  Description
  The content type of the file. One of: "image/png", "image/jpeg", "image/jpg", "image/svg+xml", "image/gif", "image/heic", or "image/heif".
- Name
  data
  Type
  string or object
  Description
  The file data encoded with base64.

The file object

{
  "createdAt": 1561687797115,
  "name": "nora_small.gif",
  "contentType": "image/gif",
  "contentLength": 1219,
  "md5digest": "019926e3f92769731547ca2ffc655bb7",
  "publicIn": [
    "note:Aa70pM075"
  ],
  "_attachments": {
    "index": {
      "content_type": "image/gif",
      "digest": "md5-AZkm4/knaXMVR8ov/GVbtw==",
      "revpos": 4,
      "data": "R0lGODlhUAA2APcAAP///wAAAAAAyAgTAAwAAABuAG8AcgBhAF8AcwBtAGEAbABsAC4AZwBpAGYAAAD8dxa1/Hcttfx3ZPoSAGz6EgAAAAAAePgSAAACAAAAABMASCAYAHgBEwD3AQAAULb8d3gBEwB4ARMAAAAAAID6EgBABhMAAm7id0e/33fo6G0ACEoXAAhKFwBMtOB3CEoXAHgBEwB4ARMACEoXAKx+33dABhMA6BdZAOjobQAM+RIAPqPedxjlYQABAAAAAQAFAHgBEwB4ARMAeAETAHgBEwAYAQEAeAETAHgBEwBU+RIAJAAAAHA5+HcAABMASA0TACQAAAC4axMALPkSAAACAADo+hIAlSv4d7g5+Hf/////+PoSACey/HdIDRMAAAAAAAAAAACoc0gAgB0YAKD5EgAAAAAA5Tj4dwAAEwB4chcAAAAAAHz5EgCIBhMAMPoSAJUr+HcgOfh3/////0D6EgBAt/x32AcTAIByFwCUchcAgHIXAAEAAAA4HhgAUCAYAEggGABoARMAAAAIAgwAAACiAKQAoVP4d5Dx/HeGU/h3mGcTAHhnEwCUchcAAAAAAAAAAAA4+hIAlSv4d0hU+Hf/////SPoSAAAAEwAHAAAAAHIXAIByFwABAAAAAWcTABDw/Hew+RIAgPoSAID6EgCVK/h3GDb4d/////+Q+hIAiVfmdwAAEwAAAAAAAQAAAF7P3ncAAAAAAQAAAADg/X9fAFMAfgAxAIByFwAAAAAASAEAAFT6EgAMAAAAsP8SAGwT6ndoHuV3/////xg2+HfcTUMAgHIXAAAAEwAAAAAAIAAAAMAqdHE16sIBAJgBOCQAAAAA15txNerCAQAAAACAAQAAyAgTAAwAAABub3JhuGsTACABAABpZgAAXgoCAF4KAgA0+xIAlSv4dwg2+Hf/////RPsSADaR5XcAABMACAAUABgBAABez953AAAAAAAAAAAAAAAAAAAAAMTARAALbBMAbNEVAA9sEwD/c0gA/////7hrEwAuwUQAC2wTACH5BAEAAAAALAAAAABQADYAQAj/AAEIHEiwoMGDCBMqXMiwocOHECEGmEgxYsKKAjECoMhxosWMHUF6LNixpMgAJDUSLMlSYciTKBe2RMhy5MCaKl1y/GjwZUqPM23uhGlzY0yePHHiXOnTJ9KnUKPezCnV6VSqFk0WfTh0o1GlV486NPl1a9mGVssCXfoTK1aaSuMOZRvWqVmpF2M23VpzKlOxeAMLHky4sOHDaLsKflu4L96Zde9yBYvUMVvFk+cyllmULMy6mYW+lUu6NMqKptsyTPs0qOSDm+Gapkx57Gmos7vWPqv2aOzBtVWGxCgcMOLPvUHT/Xqcs+O8z5tLn0498O/quK9jr4x5u3XPj7VHoH35+iN4otmHG+eutzPkrOrF6xS9FrX8yKe7h7Yf/H5y3knRF59G93mm319mueVebwe2JeB8uaGHX2pWNcicbP2R1lN0J61moW317aQfZh86GB555SHIXm6K7eacV+axCJmIJIK04XgypoaggSnut5R7dOlm13qHySVSWFddaCN1yxXnWkrV6UjUc/5V1eBeQxIpnZQTsubdij1+KWZBAQEAOw=="
    }
  },
  "_id": "file:bhi701rgp",
  "_rev": "4-21e2bcd1d6540d73b76104fe8d3a759f"
}

The file class

The File class is a wrapper class of the file, providing various methods for its operations such as loading, validation, saving, and serialization.

Methods

Name
static loadWithId(docid: string)
Type
Description
Loads a file by its ID from the local database and returns a new instance of the File.
Name
static createFromFile(file: Readonly<File>)
Type
Description
Creates a new file attachment from the provided file and returns a new instance of the File.
Name
static createFromNativeImage(nativeImage: Record<string, any>, filename?: string)
Type
Description
Creates a new file attachment from the provided native image and returns a new instance of the File.
Name
static createFromFilePath(filePath: string)
Type
Description
Creates a new file attachment from the provided file path and returns a new instance of the File.
Name
constructor(initialValues: Partial<IDFile> = {})
Type
Description
Initializes a new File instance with the given initial values. If no values are provided, it assigns default values.
Name
validate()
Type
Description
Validates the current file instance based on the predefined validation rules. If valid, returns an empty array. If not, returns the list of validation errors.
Name
save()
Type
Description
Validates and then saves the file to the local database. Throws an error if the validation fails or if there's a problem with the saving process.
Name
setFile(file: Readonly<File>)
Type
Description
Sets the file content of the current instance with the provided file.
Name
setPNGBuffer(buffer: Buffer)
Type
Description
Sets the file content of the current instance with the provided PNG buffer.
Name
getAsBase64()
Type
Description
Retrieves the file attachment's data as a base64 string.
Name
getAsBuffer()
Type
Description
Retrieves the file attachment's data as a buffer.
Name
saveFileSync(dirToSave: string)
Type
Description
Synchronously saves the file to the provided directory and returns the saved file's name.
Name
toObject()
Type
Description
Converts the file instance into a plain JavaScript object.
Name
toJson()
Type
Description
Serializes the file instance into a JSON string.
Name
toMarkdown()
Type
Description
Converts the file instance into a markdown image link format.

Import the class

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

Load a file from the database

const file = await File.loadWithId('file:9dc6a7a7')

Create a new file

const file = new File({
  name: 'My file'
})

Load from a file

const file = file.createFromFilePath('/path/to/file.png')

Change its name

file.name = 'Updated file'

Save the changes

await file.save()

Convert the file into a plain object

const object = file.toObject()

Convert the file into JSON

const json = file.toJson()

Convert the file to markdown

const markdown = file.toMarkdown()
// -> ![Image attachment](inkdrop://file:9dc6a7a7)

get(docId, options)

Retrieve a file

Retrieve a file with the given ID.

Parameters

Name
docId
Type
string
Required
Description
The file ID
Name
options
Type
object
Description
Options. See PouchDB's documentation for available options.

Returns

Returns a file if a valid file ID was provided.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const file = await db.files.get('file:bhi701rgp', { attachments: true })

Response

{
  "createdAt": 1561687797115,
  "name": "nora_small.gif",
  "contentType": "image/gif",
  "contentLength": 1219,
  "md5digest": "019926e3f92769731547ca2ffc655bb7",
  "publicIn": [
    "note:Aa70pM075"
  ],
  "_attachments": {
    "index": {
      "content_type": "image/gif",
      "digest": "md5-AZkm4/knaXMVR8ov/GVbtw==",
      "revpos": 4,
      "data": "R0lGODlhUAA2APcA...subdij1+KWZBAQEAOw=="
    }
  },
  "_id": "file:bhi701rgp",
  "_rev": "4-21e2bcd1d6540d73b76104fe8d3a759f"
}

all()

List all files

Retrieve a list of your files.

Parameters

No parameters

Returns

Returns a list of files.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const list = await db.files.all()

Response

[
  {
    createdAt: 1537774057842,
    name: 'IMG_1004 copy.JPG',
    contentType: 'image/jpeg',
    contentLength: 40020,
    md5digest: '9e00f2a9242499ccd3c47dbfa802d548',
    revpos: 1,
    _attachments: {
      index: {
        digest: 'md5-ngDyqSQkmczTxH2/qALVSA==',
        content_type: 'image/jpeg',
        revpos: 1,
        data: '...(base64)...'
      }
    }
  },
  ...
]

createId(): string

Create a file ID

Creates new file ID which is String

Parameters

No parameters

Returns

Returns a new file ID.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const fileId = await db.files.createId()

Response

"file:ak0s1ce6"

validateDocId(): boolean

Validate a file ID

Tests if the given docId is a valid file 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.files.validateDocId('file:ak0s1ce6')

Response

true

put(doc)

Create or update a file

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

Parameters

Name
doc
Type
object
Required
Description
A File 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.files.put({
  _id: 'file:9IoGtoCuv',
  "createdAt": 1561687797115,
  "name": "nora_small.gif",
  "contentType": "image/gif",
  "contentLength": 1219,
  "md5digest": "019926e3f92769731547ca2ffc655bb7",
  "publicIn": [],
  "_attachments": {
    "index": {
      "content_type": "image/gif",
      "digest": "md5-AZkm4/knaXMVR8ov/GVbtw==",
      "revpos": 4,
      "data": "R0lGODlhUAA2APcA...subdij1+KWZBAQEAOw=="
    }
  }
})

Response

{
  "ok": true,
  "id": "file:9IoGtoCuv",
  "rev": "1-a6157a5ea545c99b00ff904eef05fd9f"
}

remove(docId)

Remove a file

Deletes a file with the given file ID.

Parameters

Name
docId
Type
string
Required
Description
A file 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.files.remove("file:9IoGtoCuv")

Response

{
  "ok": true,
  "id": "file:9IoGtoCuv",
  "rev": "2-9af304be281790604d1d8a4b0f4c9adb"
}

countAll()

Request

const db = inkdrop.main.dataStore.getLocalDB()
const num = await db.files.countAll()