org-mode-connection

This package allows to read, write and sync emacs’s org-mode files.

It was developed as foundation for organic - mobile org-mode client written in React Native.

It is designed to work both in mobile and server/desktop environments.

Installation

yarn add realm promisify-node org-mode-connection

Configuration

with Node.js

var OrgApi = require('org-mode-connection').OrgApi
const realm = require('realm')
const promisify = require('promisify-node');
const fsInterface = promisify('fs')

OrgApi.configureFileAccess(fsInterface);
OrgApi.configureDb(realm);
OrgApi.connectDb();

with React Native

import OrgApi from 'org-mode-connection';
import RNFS from 'react-native-fs';
import Realm from 'realm';

OrgApi.configureFileAccess(RNFS);
OrgApi.configureDb(Realm);
OrgApi.connectDb();

Usage

Example

const query =  async() => {
    await OrgApi.clearDb()
    await OrgApi.addFile('~/org/organizer.org')
    const res = await OrgApi.getAllFilesAsPlainObject()
    console.log(res)
}
query()

Parsing node content

//import { NodeContentParser } from "org-mode-connection";
const NodeContentParser = require('org-mode-connection').NodeContentParser
const res = NodeContentParser(" *this is bold* and this /italic/\nnext line");
console.log("// Parsed lines:\n", res, "\n")
console.log("// Content of the first line:\n", res[0].content)

// Parsed lines:
 [ { type: 'regularLine',
    content: [ [Object], [Object], [Object], [Object], [Object] ] },
  { type: 'regularLine', content: [ [Object] ] } ]

// Content of the first line:
 [ { content: ' ', type: 'regularText', indexStart: 0, indexEnd: 1 },
  { type: 'boldText',
    indexStart: 1,
    indexEnd: 15,
    content: 'this is bold' },
  { content: ' and this ',
    type: 'regularText',
    indexStart: 15,
    indexEnd: 25 },
  { type: 'italicText',
    indexStart: 25,
    indexEnd: 33,
    content: 'italic' },
  { content: '',
    type: 'regularText',
    indexStart: 33,
    indexEnd: undefined } ]

Api

addFile(title)

Creates empty file in database.

Arguments:

• title: string - New file title

Results:

Promise<void>

addNodes(nodes, insertPosition, externalChange, returnAddedNodes)

Add nodes to the tree of nodes

Arguments:

• nodes: PlainOrgNode[]
• insertPosition: InsertPosition
• externalChange: boolean
• returnAddedNodes: boolean

Results:

Promise<PlainOrgNode[]>

clearDb()

Clears Database.

Results:

Promise<void>

configureDb(realm)

Configure database.

Arguments:

• realm: Realm - Realm object

Results:

void

configureFileAccess(fsIterface)

Arguments:

• fsIterface: FsInterface - Promisified file access interface

Results:

void

connectDb()

Connect database

Results:

Promise<void>

createFileFromString(name, lines)

Create file from array of strings.

Arguments:

• name: string - The name of new file
• lines: string[] - List of string raw lines

Results:

Promise<void>

deleteFileById(fileId)

Delete file from database.

Arguments:

• fileId: string - File id

Results:

Promise<void>

deleteNodeById(nodeId)

Deletes node.

Arguments:

• nodeId: string

Results:

Promise<void>

getAgendaAsPlainObject(timeRange, defaultWarningPeriod)

Returns agenda as plain object

Arguments:

• timeRange: TimeRange
• defaultWarningPeriod: number

Results:

Promise<PlainAgenda>

getAllFilesAsPlainObject()

Returns all OrgFiles as plain objects

Results:

PlainOrgFile[]

getAncestorsAsPlainObject(nodeId)

Returns all ancestors of node.

Arguments:

• nodeId: string

Results:

Promise<PlainOrgNode[]>

getExternallyChangedFiles()

Returns ids of externally changed files

Results:

Promise<ExternalFileChange[]>

getFileAsPlainObject(id)

Returns file and its nodes data as plain object.

Arguments:

• id: string - File id

Results:

Promise<PlainOrgFile>

getObjects(model, filter)

Return raw RealmResults object

Arguments:

• model: undefined - Realm model
• filter: string - Realm filter string

Results:

Promise<RealmResults>

getOrCreateNodeByHeadline(targedNode)

Gets node by headline. If node doasnt exists it is created.

Arguments:

• targedNode: { fileId: string, headline: string }

Results:

Promise<PlainOrgNode>

getRelatedNodes(nodeId)

Returns ancestors and descendants

Arguments:

• nodeId: string

Results:

Promise<PlainOrgNode[]>

getTagsAsPlainObject()

Returns list of all tags

Results:

Promise<string[]>

getTocs()

Returns all files with their child nodes

Results:

Promise<Tocs>

importFile(filepath)

Imports external file

Arguments:

• filepath: string

Results:

Promise<void>

search(searchQuery)

Search

Arguments:

• searchQuery: SearchQuery

Results:

Promise<any>

syncDb()

Sync all files

Results:

Promise<any>

syncFile(id)

Syncs file

Arguments:

• id: any - file id

Results:

Promise<any>

updateFile(id, changes)

Merges prop to file object

Arguments:

• id: string - File id
• changes: Object - New file props to merge

Results:

Promise<any>

updateNodeById(id, changes)

Merges props to node object

Arguments:

• id: string - Node id
• changes: Object - New node props to merge

Results:

Promise<any>

Types

PlainOrgFile

type PlainOrgFile = {
  id: string;
  name: string;
  size: string;
  ctime: string;
  mtime: string;
  path: string;
  title: string;
  description: string;
  metadata: string;
  category: string;
  lastSync: string;
  isChanged: boolean;
  isConflicted: boolean;
};

PlainOrgNode

type PlainOrgNode = {
    id: string;
    level: number;
    position: number;
    headline: string;
    content?: string;
    fileId: string;
    category?: string;
    todo?: string;
    priority?: string;
    drawers: string;
    tags: string[]
    timestamps: PlainOrgTimestamp[]
}

PlainOrgTimestamp

type PlainOrgTimestamp = {
    type: "active" | "inActive" | "scheduled" | "deadline";
    date: string;
    dateRangeEnd: string;
    dateRangeWithTime: boolean;
    dateWithTime: boolean;
    warningPeriod: string;
    repeater:  string;
}

PlainAgenda

type NodeTimestamp = {
  type: string;
  nodeId: string;
}

type PlainAgenda = {
  nodes: PlainOrgNodesDict;
  agendaItems: NodeTimestamp[];
  dayAgendaItems: NodeTimestamp[];
};

SearchQuery

type SearchQuery = {
  searchTerm: string;
  todos: any[];
  tags: any[];
  priorioty: string;
  isScheduled: boolean;
  hasDeadline: boolean;
};

FsInterface

type FsStat = {
    mtime: string;
    ctime: string;
    name: string;
    size: string;
}

interface FsInterface {
    write(): Promise<boolean>;
    exists(path: string): Promise<boolean>;
    read(path: string): Promise<string[]>;
    stat(path: string): Promise<FsStat>;
}

ExternalFileChange

type ExternalFileChange = {
  id: string;
  mtime: string;
};

InsertPosition

type InsertPosition = {
  fileId: string;
  nodeId?: string;
  headline?: string;
}

TimeRange

type TimeRange = {
  start: string;
  end: string;
};

Tocs

type Tocs = {
  ids: { [fileId: string]: string[] };
  data: PlainOrgNodesDict;
};

PlainOrgNodesDict

type PlainOrgNodesDict = { [nodeId: string]: PlainOrgNode };

Realm

RealmJs object.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.