sleepdiary / core

Documentation and code for manipulating sleep diaries

Sleep Diary Core Library

Documentation and code for file formats that record circadian rhythms.

Format documentation

Third-party documentation for a variety of file formats. These describe issues that implementors may face in practice, but which are not mentioned in the official documentation.

• Activity Log
• Fitbit
• Plees Tracker
• Sleep as Android
• Sleepmeter
• Spreadsheet Graph
• Spreadsheet Table
• SleepChart 1.0

The example code can translate these formats to and from Standard format, which provides a standard interface for common functionality.

JavaScript library

Each format includes example code for loading and saving documents in the relevant format. They have been packaged into a JavaScript library you can use in your own projects.

To check if the project works in your browser, try the browser-based unit tests. Then download the library and check out the library documentation.

Get Involved

I found a bug, how should I tell you?

Create a new bug report and we'll get right on it.

I'd like to request a new feature, what should I say?

Please create a new feature request. We'll try to sort out your problem.

I'd like to change the code, how do I get started?

Take a look at our getting started guide. Or if you'd like to talk to someone first, open a discussion and describe what you're planning.

License

Sleep Diary Core Library, Copyright © 2020-2022 Sleepdiary Developers

Sleep Diary Core Library comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. For details, see the license statement.

core's Issues

Publishing to node

First of all, I'm sorry for mostly abandoning the issue I opened in the old repository.

As you pointed out, a lot has changed since the end of January when I initially opened the issue.
One thing however remained mostly unchanged: There is no "practical" way of using the library in node.

What do I mean by practical? For better or worse, npm is the de facto standard for node dependency and version management. The vast, vast majority of node projects use npm. That's by no means limited to server-side projects - most modern frontend frameworks use and depend on npm modules. In other words: If you are starting any new JavaScript project using a modern stack, npm is more or less inevitable.

Now, when you find a good library - like this one - that you want to use in your npm-dependent project, you can't just npm install or yarn add it. Downloading the library and adding it to your project is more cumbersome yet still simple enough. But suddenly there's a moving part in your repository, which is managed completely different from the rest of your dependencies, and you need to keep track of it and update it.

So while it's currently not impossible to use this library in a npm-dependent project (read: most JS projects), it's a total pain in the ass to do so.

Good news: It doesn't have to be. It's very easy to publish this library to npm without touching the build system or anything else.

For this to work, the library needs to have a version number (I very strongly suggest following semver) and a name (I'd suggest @sleepdiary/core, see at the end of this issue).

All we would need to change in the repository is add a package.json that looks like this:

{
  "name": "@sleepdiary/core",
  "description": "A short and precise description",
  "version": "0.1.0",
  "main": "sleepdiary-library.min.js",
  "repository": "sleepdiary/library",
  "license": "MIT",
  "scripts": {
    "prepare": "docker run --rm -v \"$PWD\":/sleepdiary-library $(docker build -q .)"
  },
  "files": [
    "sleepdiary-library.min.js"
  ],
  "dependencies": {
    "timezonecomplete": "^5.12.4",
    "xmldom": "^0.6.0"
  }
}

That's essentially it.

In order to publish a new version of the module, you can either run npm publish, which will simply build the library, pack and publish it, or you can use something like np, an improved npm publish that also helps with versioning, release tagging, etc.

To revisit the issue of naming: I propose the syntax of @sleepdiary/<module>. The @ symbol indicates that the module belongs to the sleepdiary user (see npm scope). Moreover, the syntax allows the user to easily identify which modules belong to which project.

All three modules that are part of the sleepdiary project could be published this way, named @sleepdiary/core, @sleepdiary/info and @sleepdiary/report respectively. @sleepdiary/core is a personal suggestion, as the term library is quite ubiquitous in this context, but it could just as well be named @sleepdiary/library or anything else. Obviously, it makes sense to keep the names consistent.

To summarize: It's very little effort to implement and maintain this and it would allow for this library to be used in any npm-dependent project just as easily as any other module.