@dimerapp/datastore
Datastore to store dimer websites as JSON
Last updated 2 years ago by virk .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @dimerapp/datastore 
SYNC missed versions from official npm registry.
Dimer App

Dimer is an open source project and CMS to help you publish your documentation online.


We believe every project/product is incomplete without documentation.
We want to help you publish user facing documentation, without worrying about tools or code to write.


travis-image npm-image

Dimer datastore

Dimer datastore saves the websites, their versions and documents for each version.

The datastore operates on JSON flat files and exposes API to mutate and read the store.

Installation

npm i @dimerapp/datastore

# Yarn
yarn add @dimerapp/datastore

Data Structure

Following is the data structure of all the nodes inside the store. The required properties are required to mutate the store.

Site

Site is a given website, with it's own domain.

Key Value Required Description
domain String NO The domain of the website. If it's stored on dimer servers, then this is the subdomain test.dimerapp.com
cname String NO CNAME to dimer subdomain
settings Object NO An arbitrary object containing website settings. This is usually used by the themes

Zones

Zones are the way to divide sections of your website docs into multiple top levels. For example: Guides, API, FAQ's and so on.

Key Value Required Description
slug (unique) String Yes The slug to be used for uniquely identifying the zone.
name String No The display name for the zone
versions Array Yes The versions for the zone

Versions

Versions for a given zone. When your are not using zones, then the versions become the part of a virtual zone.

Key Value Required Description
no (unique) String YES The version number. It must be URL friendly
name String No Version no will be used as the name if not defined.
default Boolean No Is this the default version for documentation. If not defined, the greatest number will be considered as the default version.
depreciated Boolean No Is this version depreciated
draft Boolean No Is this version a draft

Docs

The documentation node associated with a version always.

Key Value Required Description
content Object Yes The object of nodes, returned by @dimerapp/markdown.
permalink (unique) String Yes The unique permalink for the doc. This is the URL people will visit to read the doc
title String Yes The title for the document. First h1 will be used if missing.
jsonPath (unique) String Yes The relative path, where the content should be saved
summary String No The document social summary. If missing will be fetched from the content.
redirects Array[String] No An array of permalinks to be redirected to this document.

Usage

After installation you can grab the datastore as follows and save documents.

const Datastore = require('@dimerapp/datastore')
const Context = require('@dimerapp/context')

const ctx = new Context(__dirname)
const store = new Datastore(ctx)

await store.load()

load(clean = false)

Load the data store to start mutating it, if store is not loaded, hard exceptions will be raised.

Also when you pass clean=true, it will load the store from a clean slate. It is helpful, when you want to build documentation from scratch.

await store.load()

// from clean slate

await store.load(true)

saveDoc(zoneSlug, versionNo, filePath, doc)

Save a new doc to the datastore.

  • The slug for the zone. If missing, it will be created on the fly.
  • If the version is missing, it will be created on the fly.
  • If filePath exists, the doc will be updated.
  • If permalinkexists, an exception will be raised.
const markdown = new Markdown('# Hello world')
const content = await markdown.toJSON()

// save actual doc
await store.saveDoc(
  'guides',
  '1.0.0',
  'introduction.md',
  {
    permalink: 'introduction',
    content: content
  }
)

// update meta data to database
await store.persist()

removeDoc(zoneSlug, versionNo, filePath)

Remove doc from the store.

await store.removeDoc('guides', '1.0.0', 'introduction.md')

// update meta data to database
await store.persist()

syncZones(zones)

Syncs the zones inside the db. Also versions for each zone will be synced automatically. Each zone will have a diff node for versions too.

const { added, updated, removed } = await store.syncZones(zones)
console.log(added.versions) // { added: [], updated: [], removed: [] }

syncVersions(zoneSlug, versions)

Sync an array of versions with the existing one's. Since all versions are saved inside the config dimer.json file, it is impossible to detect which version was added and which was removed to perform individual operations like add, remove. For the very same reason, datastore exposes the API to sync them.

await store.syncVersions('guides', [
 {
   no: 'master',
   name: 'Version master',
   default: true
 },
 {
   no: 'v4.0',
   name: 'Version 4.0'
 },
 {
   no: 'v3.0',
   name: 'Version 3.0',
   depreciated: true
 }
])

// update meta data to database
await store.persist()

getVersions(zoneSlug)

Returns an array of saved versions.

store.getVersions('guides')

getTree(zoneSlug, versionNo, limit = 0, withContent = false, attachVersion = false)

Get an array of all the docs. Ideally you want this array to create a navigation menu and then on each request, you can ask for the doc content. However...

  • You can pass withContent=true and the array will have the actual content for the doc too.
  • Setting limit=0 will return all the docs.
  • All docs will be grouped by categories.
  • When attachVersion=true. Each doc will contain it's version node.
const tree = await store.getTree('guides', 'v4.0')

// output
[
 {
   category: 'Getting started',
   docs: [{
     permalink: ''
   }]
 }
]

getDoc(zoneSlug, versionNo, filePath, attachVersion = false)

Returns the doc meta data and it's content.

  • When attachVersion=true. Doc will contain it's version node.
const doc = await store.getDoc('guides', 'v4.0', 'introduction.md')

getDocByPermalink(zoneSlug, versionNo, permalink, attachVersion = false)

Returns the doc by it's permalink.

  • When attachVersion=true. Doc will contain it's version node.
const doc = await store.getDocByPermalink('guides', 'v4.0', '/introduction')

redirectedPermalink(zoneSlug, versionNo, permalink)

Returns the new permalink at which the doc must be redirected.

const redirectTo = store.redirectedPermalink('guides', 'v4.0', '/old-introduction')

if (redirectTo) {
  // redirect to this location
}

syncConfig(config)

Sync the config file with the datastore.

await store.syncConfig(require('./dimer.json'))

getConfig

Returns the synced config

const config = store.getConfig()

Search

The datastore builds a search index based on elasticlunr, which can be used for indexing a individual version and then performing search queries for same.

ALWAYS MAKE SURE TO CREATE SEARCH INDEXES AT LAST. SAVING A NEW DOC WILL NOT UPDATE THE INDEX.

await store.indexVersion('guides', 'v4.0')

And then later search

const results = await store.search('guides', 'v4.0', 'Yaml')

Following will be the output of search results

[
  {
    ref: '/yaml-front-matter',
    title: {
      score: 3.10,
      marks: [
        {
          type: 'raw',
          text: 'What is'
        },
        {
          type: 'mark',
          text: 'Yaml'
        },
        {
          type: 'raw',
          text: 'frontmatter'
        }
      ]
    },
    body: [
      {
        score: 2.984,
        marks: [{
          type: 'mark',
          text: 'Yaml '
        },
        {
          type: 'raw',
          text: 'front matter is used for'
        }]
      }
    ]
  }
]

Search languages

The datastore has support for multiple languages to create the search index. Following is the list of allowed and supported languages.

English en is the default language.

  • da (Danish)
  • de (German)
  • du (Dutch)
  • es (Spanish)
  • fi (Finnish)
  • fr (French)
  • hu (Hungarian)
  • it (Italian)
  • ja (Japanese)
  • no (Norwegian)
  • pt (Portuguese)
  • ro (Romanian)
  • ru (Russian)
  • sv (Swedish)
  • th (Thai)
  • tr (Turkish)
await store.indexVersion('guides', 'v4.0', 'de')

If your content is written in the mix of multiple languages, then you can pass an array of languages instead.

await store.indexVersion('guides', 'v4.0', ['de', 'en'])

Change log

The change log can be found in the CHANGELOG.md file.

Contributing

Everyone is welcome to contribute. Please take a moment to review the contributing guidelines.

Authors & License

thetutlage and contributors.

MIT License, see the included MIT file.

Current Tags

  • 3.0.3                                ...           latest (2 years ago)

26 Versions

  • 3.0.3                                ...           2 years ago
  • 3.0.2                                ...           2 years ago
  • 3.0.1                                ...           2 years ago
  • 3.0.0                                ...           2 years ago
  • 2.0.1                                ...           2 years ago
  • 2.0.0                                ...           2 years ago
  • 1.0.19                                ...           2 years ago
  • 1.0.18                                ...           2 years ago
  • 1.0.17                                ...           2 years ago
  • 1.0.16                                ...           2 years ago
  • 1.0.15                                ...           2 years ago
  • 1.0.14                                ...           2 years ago
  • 1.0.13                                ...           2 years ago
  • 1.0.12                                ...           2 years ago
  • 1.0.11                                ...           2 years ago
  • 1.0.10                                ...           2 years ago
  • 1.0.9                                ...           2 years ago
  • 1.0.8                                ...           2 years ago
  • 1.0.7                                ...           2 years ago
  • 1.0.6                                ...           2 years ago
  • 1.0.5                                ...           2 years ago
  • 1.0.4                                ...           2 years ago
  • 1.0.3                                ...           2 years ago
  • 1.0.2                                ...           2 years ago
  • 1.0.1                                ...           2 years ago
  • 1.0.0                                ...           2 years ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 1
Last Month 1
Dependencies (9)
Dev Dependencies (11)

Copyright 2014 - 2016 © taobao.org |