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 observablestate
andattributes
.Collection
: MultipleModel
s stored by URL, with an overall observablestate
Relationship
: Describes how to move from oneCollection
to another.Api
: MultipleCollection
s 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 <: State = reaches : Promise Model = state : 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 : 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 : 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 callingfetch
.RemoteCollection
represents a list endpoint like/api/book/
. It has additional methodswithData
andwithParam
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 aLocalModel
and then becomes whatever model is generated by thecreate
function you supply it.
Until more docs are available, here is a concise summary of most bits:
RemoteModel : url : String -> ModelRemoteCollection : url : String relationships : ... -> CollectionRemoteApi : url : String relationships : ... -> Api LocalModel : attributes: ... -> ModelNewModel : 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.