org-mode-connection

#+TITLE: org-mode-connection

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

It was developed as foundation for [[https://github.com/bnankiewicz/organic][organic]] - mobile org-mode client written in React Native.

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

• Installation

#+BEGIN_SRC sh yarn add realm promisify-node org-mode-connection #+END_SRC

• Configuration

** with Node.js

#+name: setup #+BEGIN_SRC js :results output 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(); #+END_SRC

** with React Native #+BEGIN_SRC javascript import OrgApi from 'org-mode-connection'; import RNFS from 'react-native-fs'; import Realm from 'realm';

OrgApi.configureFileAccess(RNFS); OrgApi.configureDb(Realm); OrgApi.connectDb(); #+END_SRC

• Usage

** Example

#+BEGIN_SRC js :results output :noweb yes const query = async() => { await OrgApi.clearDb() await OrgApi.addFile('~/org/organizer.org') const res = await OrgApi.getAllFilesAsPlainObject() console.log(res) } query() #+END_SRC

** Parsing node content #+name: parse-example-content #+BEGIN_SRC js :results output code :noweb yes //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) #+END_SRC

#+BEGIN_SRC js // 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 } ] #+END_SRC

• Api ** addFile(/title/) Creates empty file in database.

=Arguments=:

• title: string - New file title

=Results=:

Promise

** addNodes(/nodes/, /insertPosition/, /externalChange/, /returnAddedNodes/) Add nodes to the tree of nodes

=Arguments=:

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

=Results=:

Promise<[[#PlainOrgNode][PlainOrgNode]][]>

** clearDb() Clears Database.

=Results=:

Promise

** configureDb(/realm/) Configure database.

=Arguments=:

• realm: [[#Realm][Realm]] - Realm object

=Results=:

void

** configureFileAccess(/fsIterface/) =Arguments=:

• fsIterface: [[#FsInterface][FsInterface]] - Promisified file access interface

=Results=:

void

** connectDb() Connect database

=Results=:

Promise

** 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

** deleteFileById(/fileId/) Delete file from database.

=Arguments=:

• fileId: string - File id

=Results=:

Promise

** deleteNodeById(/nodeId/) Deletes node.

=Arguments=:

• nodeId: string

=Results=:

Promise

** getAgendaAsPlainObject(/timeRange/, /defaultWarningPeriod/) Returns agenda as plain object

=Arguments=:

• timeRange: [[#TimeRange][TimeRange]]
• defaultWarningPeriod: number

=Results=:

Promise<[[#PlainAgenda][PlainAgenda]]>

** getAllFilesAsPlainObject() Returns all OrgFiles as plain objects

=Results=:

[[#PlainOrgFile][PlainOrgFile]][]

** getAncestorsAsPlainObject(/nodeId/) Returns all ancestors of node.

=Arguments=:

• nodeId: string

=Results=:

Promise<[[#PlainOrgNode][PlainOrgNode]][]>

** getExternallyChangedFiles() Returns ids of externally changed files

=Results=:

Promise<[[#ExternalFileChange][ExternalFileChange]][]>

** getFileAsPlainObject(/id/) Returns file and its nodes data as plain object.

=Arguments=:

• id: string - File id

=Results=:

Promise<[[#PlainOrgFile][PlainOrgFile]]>

** getObjects(/model/, /filter/) Return raw RealmResults object

=Arguments=:

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

=Results=:

Promise<[[#RealmResults][RealmResults]]>

** getOrCreateNodeByHeadline(/targedNode/) Gets node by headline. If node doasnt exists it is created.

=Arguments=:

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

=Results=:

Promise<[[#PlainOrgNode][PlainOrgNode]]>

** getRelatedNodes(/nodeId/) Returns ancestors and descendants

=Arguments=:

• nodeId: string

=Results=:

Promise<[[#PlainOrgNode][PlainOrgNode]][]>

** getTagsAsPlainObject() Returns list of all tags

=Results=:

Promise<string[]>

** getTocs() Returns all files with their child nodes

=Results=:

Promise<[[#Tocs][Tocs]]>

** importFile(/filepath/) Imports external file

=Arguments=:

• filepath: string

=Results=:

Promise

** search(/searchQuery/) Search

=Arguments=:

• searchQuery: [[#SearchQuery][SearchQuery]]

=Results=:

Promise

** syncDb() Sync all files

=Results=:

Promise

** syncFile(/id/) Syncs file

=Arguments=:

• id: any - file id

=Results=:

Promise

** updateFile(/id/, /changes/) Merges prop to file object

=Arguments=:

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

=Results=:

Promise

** updateNodeById(/id/, /changes/) Merges props to node object

=Arguments=:

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

=Results=:

Promise

• Types

** PlainOrgFile :PROPERTIES: :CUSTOM_ID: PlainOrgFile :END: #+BEGIN_SRC typescript 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; }; #+END_SRC

** PlainOrgNode :PROPERTIES: :CUSTOM_ID: PlainOrgNode :END: #+BEGIN_SRC typescript 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[] } #+END_SRC

** PlainOrgTimestamp :PROPERTIES: :CUSTOM_ID: PlainOrgTimestamp :END: #+BEGIN_SRC typescript type PlainOrgTimestamp = { type: "active" | "inActive" | "scheduled" | "deadline"; date: string; dateRangeEnd: string; dateRangeWithTime: boolean; dateWithTime: boolean; warningPeriod: string; repeater: string; } #+END_SRC

** PlainAgenda :PROPERTIES: :CUSTOM_ID: PlainAgenda :END: #+BEGIN_SRC typescript type NodeTimestamp = { type: string; nodeId: string; }

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

** SearchQuery :PROPERTIES: :CUSTOM_ID: SearchQuery :END: #+BEGIN_SRC typescript type SearchQuery = { searchTerm: string; todos: any[]; tags: any[]; priorioty: string; isScheduled: boolean; hasDeadline: boolean; }; #+END_SRC

** FsInterface :PROPERTIES: :CUSTOM_ID: FsInterface :END: #+BEGIN_SRC typescript type FsStat = { mtime: string; ctime: string; name: string; size: string; }

interface FsInterface { write(): Promise; exists(path: string): Promise; read(path: string): Promise<string[]>; stat(path: string): Promise; } #+END_SRC ** ExternalFileChange :PROPERTIES: :CUSTOM_ID: ExternalFileChange :END: #+BEGIN_SRC typescript type ExternalFileChange = { id: string; mtime: string; }; #+END_SRC

** InsertPosition :PROPERTIES: :CUSTOM_ID: InsertPosition :END: #+BEGIN_SRC typescript type InsertPosition = { fileId: string; nodeId?: string; headline?: string; } #+END_SRC

** TimeRange :PROPERTIES: :CUSTOM_ID: TimeRange :END: #+BEGIN_SRC typescript type TimeRange = { start: string; end: string; }; #+END_SRC

** Tocs :PROPERTIES: :CUSTOM_ID: Tocs :END: #+BEGIN_SRC typescript type Tocs = { ids: { [fileId: string]: string[] }; data: PlainOrgNodesDict; }; #+END_SRC

** PlainOrgNodesDict #+BEGIN_SRC typescript type PlainOrgNodesDict = { [nodeId: string]: PlainOrgNode }; #+END_SRC

** Realm :PROPERTIES: :CUSTOM_ID: Realm :END: 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/.