JSSR draft

jssr-draft.md

JSSR - JavaScript Standards Recommendation

Mind: this is a draft

Why?

I have found PHP's PSRs to be a very good idea when it comes to having some sorts of standards for commonly performed tasks. Wheter it's logging, caching or performing HTTP calls.

What are PSRs? Here's a short description taken from Wikipedia:

(...) specification (...) [that] serves the standardization of programming concepts in PHP. The aim is to enable interoperability of components and to provide a common technical basis for implementation of proven concepts for optimal programming and testing practices.

In other words: if some logging modules follow that specification, one can easily exchange them in the application, as they follow the same API, provided by the interface(s).

Another reason, that I have observed, is that JavaScript ecosystem has gazillion of modules that are about the same thing (e.g. logger), but work differently, or have different API, or both. Switching from one to another might be a cumbersome task.

Why would anyone want to replace one module with another? There can be multiple reasons:

• the author of the module is not maintaining it anymore
• other module is safer
• or faster
• or smaller
• or ... (you name it)

How?

The idea would be to provide sets of interfaces, similar to PHP ones, in TypeScript.

Example

For instance, a logger interface. It exposes eight methods to write logs to the eight RFC 5424 levels (debug, info, notice, warning, error, critical, alert, emergency).

(I am very new to TypeScript, so pardon any mistakes I could have made)

interface Logger {
    /**
     * System is unusable.
     */
    emergency(message: string): void;
    
    /**
     * Action must be taken immediately.
     *
     * Example: Entire website down, database unavailable, etc. This should trigger the SMS alerts and wake you up.
     */
    alert(message: string): void;
    
    /**
     * Critical conditions.
     *
     * Example: Application component unavailable, unexpected exception.
     */
    critical(message: string): void;
    
    /**
     * Runtime errors that do not require immediate action but should typically be logged and monitored.
     */
    error(message: string): void;
    
    /**
     * Exceptional occurrences that are not errors.
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong.
     */
    warning(message: string): void;
    
    /**
     * Normal but significant events.
     */
    warning(message: string): void;
    
    /**
     * Interesting events.
     *
     * Example: User logs in, SQL logs.
     */
    info(message: string): void;
    
    /**
     * Detailed debug information.
     */
    debug(message: string): void;
    
    /**
     * Logs with an arbitrary level.
     */
    log(level: LogLevel, message: string): void;
}

enum LogLevel {
    EMERGENCY = 'emergency',
    ALERT     = 'alert',
    CRITICAL  = 'critical',
    ERROR     = 'error',
    WARNING   = 'warning',
    NOTICE    = 'notice',
    INFO      = 'info',
    DEBUG     = 'debug'
}

TODO

• get more people here, this needs discussion
  • advertise that (on Twitter, Reddit, ...)
• provide more examples, or even better, ready to clone repository