SolidState.js

https://github.com/kennknowles/solidstate.js

A high-level & highly automatic REST client for Javascript with a dramatically simple & fluent API.

Quick Intro

This module builds upon Backbone, Knockout and When, providing an even more convenient interface for accessing your backend API.

• Model: A single resource with observable state and attributes.
• Collection: Multiple Models stored by URL, with an overall observable state
• Relationship: Describes how to move from one Collection to another.
• Api: Multiple Collections stored by name with relationships built in.

What you will not find elsewhere:

• Fluent interfaces, such as RemoteCollection({ url: url }).withData({age: 45}).withRelatedSubresources('friends')
• Observable state machines for all classes, so displaying spinners, layering on models, is trivial.
• The Api class that discovers all your collections automatically from your backend root endpoint (current only Tastypie)

Interface

Each "interface" is a function that wraps an implementation to provide an extended interface, as with underscore and jQuery.

Here is a concise summary of the interfaces, where * means "anything" and everything else is as you might expect.

URL = String

State <: Observable ("initial" | "ready" | "fetching" | "saving")
State = {
  reaches : Promise ()
}

Model = {
  state       : observable ( "initial" | "ready" | "fetching" | "saving")
  attributes  : observable { String: observable * }
  fetch       : () -> Model // self
  save        : () -> Model // self

  relatedCollection : String -> Collection
  relatedModel      : String -> Model

  withState               : observable String -> Model
  withAttributes          : observable { String: observable * } -> Model
  withSubresourcesFrom    : {String: Collection | {URL: *}} -> Model
}


Collection = {
  state    : observable ( "initial" | "ready" | "fetching")
  models   : observable {URL : Model}
  fetch    : () -> Collection // self
  newModel : () -> Model

  when : String -> (() -> ()) -> () // first param is goal state, not event!

  relatedCollection       : String -> Collection

  withRelationships       : ((Collection, String) -> Collection) -> Collection
  withSubresourcesFrom    : {String: Collection | {URL: *}} -> Model
  withRelatedSubresources : (String, ...) -> Model
}

Relationship = {
  relatedCollection : (Collection, Collection) -> Collection // relatedCollection(from, to) adds the right filters
}

Api = {
  state       : observable ("initial" | "fetching" | "ready")
  collections : observable {String: Collection}
  fetch       : () -> Api

  when : String -> (() -> ()) -> () // first param is goal state, not event!

  relatedCollection :: (String, String, Collection) -> Collection  // Keyed on source name, attribute name, and taking particular src collection too
}

Implementations

The most important implementations are RemoteModel, RemoteCollection, and RemoteApi, which form a REST API client.

• RemoteApi represents your /api/. It understands Django Tastypie schemas and can generate all of your collections simply by calling fetch.
• RemoteCollection represents a list endpoint like /api/book/. It has additional methods withData and withParam for adjusting the HTTP requests.
• RemoteModel represents a particular resource like /api/book/25.

In addition, there are the following

• LocalModel which is just a wrapper around a dictionary of attributes, for mocking, etc.
• NewModel which starts as a LocalModel and then becomes whatever model is generated by the create function you supply it.

Until more docs are available, here is a concise summary of most bits:

RemoteModel      : { url : String } -> Model
RemoteCollection : { url : String, relationships : ... } -> Collection
RemoteApi        : { url : String, relationships : ... } -> Api

LocalModel : { attributes: ... } -> Model
NewModel : { attributes: ..., create: ({attributes:...}) -> Model } -> Model

// This could be cleaned up a bit...
JoinRelationship : { 
  type               : "toOne" | "toMany" | "fromOne" | "fromMany",
  sourceKey          : String | ({String: observable *} -> String), // Either an attribute or a way to extract the transformed attribute
  sourceKeyTransform : ("uri" | undefined | (String -> String)),    // either "uri" 
  destFilter         : String,
} -> Relationship

Caveats (Special Features?)

• Though used in large projects, SolidState.js is still new. It might be a bit crufty!
• There is no attempt to support module systems other than AMD / RequireJS. Pull requests are welcome.
• There is a certain amount of direct support for Django Tastypie. This is a "feature" but means that it may be less helpful for other backends, without some customization. Again, pull requests welcome.

Copyright & License

Copyright 2012 Kenneth Knowles

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.