andrew-sayers/sleep-diary-formats

Experimental repository for sleep-diary-formats

sleep-diary-formats's Issues

State of the project and roadmap

Hey,

first of all, I'm really excited to see other people working on Non-24 and circadian sleep disorder related projects, and I'm impressed by the work you have already done with this project.

Since I'm strongly considering contributing to the project, I'd like to know what the current state of the project is and what your roadmap for the future looks like.

One quite noticeable thing is the confusing structure of the project: Manually curated files are mixed up with computer-generated files (as in doc/), the repository serves the source code of the library, the source code of the documentation, the compiled library and the compiled documentation all in one place. For someone who's inexperienced with your code base, it's pretty difficult to get an overview.

Would you consider restructuring the project? I can make some suggestions, but in the end you are currently the project maintainer and would need to adopt to a new project structure.

The second thing I noticed is the library API itself. Don't get me wrong, it's certainly usable. But it's very unintuitive since it significantly differs from common JavaScript practices. Moreover it's written completely in CommonJS, which is completely fine, but I think the project could certainly benefit from a more modern toolchain.

Then again, it depends on what your plans are for this project.
In my opinion, restructuring both the project and the library's codebase could significantly improve the development workflow and would make it easier for others to contribute. I think this project could be a rock solid basis for many other projects to come, but for that it would need to be more accessible and mature.

I'll admit that's a lot of critique so far, but I want to stress that I really like everything you have done with this project so far and I appreciate your contribution to the Non-24 / CSRD community ❤️

Changing the standard format's timestamp format from Unix to ISO 8601

The problem:

The standard format currently uses Unix Epoch timestamps, which have a couple of significant disadvantages.

1. They are not human-readable

The integer used by Unix timestamps cannot be read by humans without an utility to convert it to a conventional time and date.
Other than the duration field (which I hope to address in another issue), every field of the format is human-readable, and I think that's a useful property we should aim to keep.

2. Unix timestamps require documentation

Unix timestamps are not standardized. Some representations describe the time passed since January 1st 1970 as seconds, others as milliseconds. This can lead to confusion and implementation errors of all sorts.

Ideally, the standard format should use a human-readable, self-documenting, unambiguous, standardized timestamp format.

The solution:

ISO 8601 to the rescue.

ISO 8601 is a standardized, widely used timestamp format. Some of its advantages include:

• it's human-readable (someone can look at them and understand the date and time)
• it's standardized and self-documenting (no additional documentation required, no room for implementation errors)
• it's supported by pretty much every modern programming language (either directly as part of the language or as a standard library)
• can also represent the time zone of an event
• natively supported in JavaScript

The only downsides to ISO 8601 I could think of are:

• it takes up slightly more storage (which shouldn't be an issue for the scope of this format)
• it's harder to implement an ISO 8601 converter from scratch compared to Unix timestamps that can be calculated quite easily (but since pretty much every language supports ISO 8601 timestamps either natively or through standard libraries, this shouldn't be a problem)

Since ISO 8601 also incorporates the time zone of the event, I see no reason to keep start_timezone and end_timezone. This way a developer can directly parse the timestamp and use the utilities provided by most programming languages to evaluate the data.

I'll try and work on a PR within the next few days, and I'm open to any arguments in favor of Unix timestamps.