slender_data 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ee33cc4f9d5919b3ff1047221a190414a19069d2
-  data.tar.gz: a1a39aea719c62de60004c370a4ba7864cdf7e9f
+  metadata.gz: 039f8fdfcd726201c423f28a0f3bb5128d6c82f9
+  data.tar.gz: e9ae11877f924d70673ea8d87367cb5230e34143
 SHA512:
-  metadata.gz: 540378e81d3795a257a90f8fc22ca6adc6225f6e9cf3daa8613ce818572ccdfa0d7fb38196d0db346dbafadcc1bcb0abd672bfa35afcf3272b0899d53edaf9c4
-  data.tar.gz: 9a07f6eca0c9672edfdb7a81ce66b22afcc602233ac80c9550e212ff98129578ba2577ddf36a7da51e5052e6922970467f112137398bd011f775f5df2d89786c
+  metadata.gz: d737ee000404b4036b927a0d2fd523dcc8367c5052c859650dca758f7e1398043ad5ac87ae819abbc5d10ae8cd3a5effb19e6588a7c2195a37a0c2a63415f203
+  data.tar.gz: 70c48cb3d6b8aed81308ad2333f24b2e0744a220b3a705160e080bbfd45cf4ae5688060c2b5df72e99b8b5fb7df1afc7935cdd00cf5c9226477005e8cee72515

data/app/assets/javascripts/slender_data.coffee

@@ -0,0 +1,14 @@
+#= require_self
+#= require ./slender_data/tools
+#= require ./slender_data/persistence_manager
+
+window.slender_data or= {}
+
+
+# Makes sure the given query is an instance of the given query class.
+# If not, creates an instance of the given query class from the given query.
+slender_data.querify = (query, clazz, params) ->
+  if query instanceof clazz
+    query
+  else
+    new clazz query, params

data/app/assets/javascripts/slender_data/brest_loader.coffee

@@ -0,0 +1,139 @@
+#= require slender_data/queries/multi_query
+#= require slender_data/queries/single_query
+#= require slender_data/parameterizable
+
+
+# High-level SDK for CRUD operations against a BREST API.
+#
+# Takes arguments as Queries (SingleQuery or MultiQuery),
+# and expects the server to return self-describing data in raw query form,
+# i.e. as "user: {...}" instead of just "{...}" when returning a user object.
+# The server responses are forwarded as-is to the callers.
+class slender_data.BrestLoader extends slender_data.Parameterizable
+
+  constructor: (params) ->
+    super params
+
+    # The base url of the BREST API on the server.
+    #
+    # Example: provide '/api' to access users at '/api/users'.
+    @base_url = params.base_url or ''
+
+
+  # Creates the entry described by the given query on the server.
+  create: (entry, callback) ->
+    data = {}
+    data[@entry_name] = entry
+
+    jQuery.ajax
+      url: @entries_url()
+      type: 'POST'
+      data: data
+      success: callback
+
+
+  # Creates the entries described by the given multi-query on the server.
+  create_many: (entries, callback) ->
+    data = {}
+    data[@entries_name] = entries
+
+    jQuery.ajax
+      url: @entries_url()
+      type: 'POST'
+      data: data
+      success: callback
+
+
+  # Deletes the entry described by the given query on the server.
+  delete: (query, callback) ->
+    query = @_querify_single query
+    jQuery.ajax
+      url: @entry_url(query)
+      type: 'DELETE'
+      success: callback
+
+
+  # Deletes the entries described by the given multi-query on the server.
+  delete_many: (multi_query, callback) ->
+    multi_query = @_querify_multi multi_query
+    data = {}
+    data[@ids_name] = multi_query.ids()
+    jQuery.ajax
+      url: @entries_url()
+      type: 'DELETE'
+      data: data
+      success: callback
+
+
+  # Returns the url to access a single entry.
+  entry_url: (query) ->
+    query = @_querify_single query
+    "#{@base_url}/#{@entries_name}/#{query.id()}.json"
+
+
+  # Returns the url to access the collection of entries.
+  entries_url: ->
+    @_entries_url_result or= "#{@base_url}/#{@entries_name}.json"
+
+
+  # Merges the entries described by the given ids
+  # into a new entry with the given data.
+  merge: (old_entry_ids, new_entry, callback) ->
+    data =
+      old_snippet_ids: old_entry_ids
+      merged_snippet_data: new_entry
+    $.ajax
+      url: "#{@base_url}/#{@entries_name}/merge.json"
+      type: 'POST'
+      data: data
+      success: callback
+
+  # Fetches the entry with the given key from the server.
+  read: (query, callback) ->
+    query = @_querify_single query
+    jQuery.get @entry_url(query), callback
+
+
+  # Loads all objects from the server.
+  # Provides the given params as parameters to the GET request.
+  read_many: (multi_query, callback) ->
+    multi_query = @_querify_multi multi_query
+    data = {}
+    data[multi_query.ids_name] = multi_query.ids().join(' ')
+    jQuery.ajax
+      url: @entries_url()
+      type: 'GET'
+      cache: no
+      data: data
+      success: callback
+
+
+  # Updates the given entry on the server.
+  #
+  # The entry can be a partial diff of the real entry,
+  # but must contain the key column.
+  update: (entry, callback) ->
+    data = {}
+    data[@entry_name] = entry
+
+    jQuery.ajax
+      url: @entry_url(entry: entry)
+      type: 'PUT'
+      data: data
+      success: callback
+
+
+  # Updates the given entries on the server.
+  #
+  # The entry can be a partial diff of the real entry,
+  # but must contain the key column.
+  update_many: (entries, callback) ->
+    data = {}
+    data[@entries_name] = entries
+
+    jQuery.ajax
+      url: @entries_url()
+      type: 'PUT'
+      data: data
+      success: callback
+

data/app/assets/javascripts/slender_data/cache.coffee

@@ -1,5 +1,6 @@
 # A generic cache.
 # Stores key-value pairs.
+# This is pretty much a more comfortable hash object.
 class slender_data.Cache
 
   constructor: ->
@@ -22,20 +23,18 @@ class slender_data.Cache
   # Looks up several entries at once.
   # Returns a hash of found entries, and a list of missing entries.
   get_many: (keys) ->
-    result = { found: {}, missing: [] }
+    found = []
+    missing = []
     for key in keys
-      do (key) =>
-        value = @cache[key]
-        if value
-          result.found[key] = value
-        else
-          result.missing.push key
-    result
-  getMany: Cache::get_many
+      if (entry = @cache[key])
+        found.push entry
+      else
+        missing.push key
+    found: found, missing: missing
 
 
   # Returns the number of cached objects.
-  length: () ->
+  length: ->
     slender_data.object_length @cache
 
 
@@ -47,17 +46,3 @@ class slender_data.Cache
   # Removes all entries with the given keys.
   remove_many: (keys) ->
     @remove(key) for key in keys
-
-
-  # Replaces the cache with the given data.
-  # When 'key' is given, treats 'data' as an array of objects, and indexes each element by the given key.
-  # When 'key' is not given, treats 'data' as an already indexed hash object.
-  replace_all: (data, key) ->
-    if key
-      # Key given --> index the data array.
-      @add(entry[key], entry) for entry in data
-    else
-      # Key not given --> use data as the new cache.
-      @cache = data
-  replaceAll: Cache::replace_all
-

data/app/assets/javascripts/slender_data/entry_store.coffee

@@ -0,0 +1,107 @@
+#= require slender_data/query_cache
+#= require slender_data/queries/single_query
+#= require slender_data/queries/multi_query
+#= require slender_data/parameterizable
+
+
+# Stores JSON data objects, and tracks changes to them.
+class slender_data.EntryStore extends slender_data.Parameterizable
+
+  constructor: (params) ->
+    super params
+
+    # Unmodified copies of the serverside data.
+    @server_data = new slender_data.QueryCache params
+
+    # Replicas of the server data, to be modified by the client.
+    @client_data = new slender_data.QueryCache params
+
+
+  # Adds the given entry to the caches.
+  # Treats the given entry as coming from the server.
+  add: (entry) ->
+    @server_data.add entry
+    @client_data.remove entry
+
+    # Must return undefined, since we don't want to
+    # create the client entry yet to save memory and CPU,
+    # and the user should not be mislead by a returned server entry.
+    return
+
+
+  # Adds the given data objects to the server cache.
+  add_many: (entries) ->
+    @add(entry) for entry in entries
+    return  # Should not return anything.
+
+
+  # Removes the entry corresponding to the given query
+  # from this DataStore.
+  delete: (entry) ->
+    @client_data.remove entry
+    @server_data.remove entry
+
+
+  # Removes the entries corresponding to the given multi-query
+  # from this DataStore.
+  delete_many: (entries) ->
+    @client_data.remove_many entries
+    @server_data.remove_many entries
+
+
+  # Returns an object that contains only the changed attributes
+  # of the entry destribed by the given query.
+  # Returns false if the entry is not changed.
+  entry_changes: (entry) ->
+    server_version = @server_data.get entry: entry
+    changes = slender_data.object_diff server_version, entry
+    if slender_data.object_length(changes) > 0
+      changes[@id_name] = entry[@id_name]
+      changes
+    else
+      false
+
+
+  # Returns an array containing only the changed objects.
+  # Each object contains only the changed columns + key column.
+  entries_changes: (entries) ->
+    result = []
+    for entry in entries
+      if (entry_changes = @entry_changes entry)
+        result.push entry_changes
+    result
+
+
+  # Returns the entry described by the given query,
+  # or undefined if it does not exist in any of the caches.
+  get: (query) ->
+    query = @_querify_single query
+
+    # Try to use client_data cache.
+    unless (result = @client_data.get query)
+
+      # No data in client cache --> try to use server cache.
+      if (server_entry = @server_data.get query)
+        result = @client_data.add_clone server_entry
+
+    result
+
+
+  # Returns the entries described by the given multi-query,
+  # as well as a list of entries not found.
+  get_many: (multi_query) ->
+    found = []
+
+    # Load client-side data.
+    client_results = @client_data.get_many @_querify_multi(multi_query)
+    $.merge found, client_results.found
+    missing_query = client_results.missing
+
+    if not missing_query.empty()
+      # Some entries not in client cache --> look in server cache.
+      server_results = @server_data.get_many missing_query
+      $.merge found, @client_data.add_clones(server_results.found)
+      missing_query = server_results.missing
+
+    found: found, missing: missing_query
+

data/app/assets/javascripts/slender_data/loading_indicator.coffee

@@ -0,0 +1,28 @@
+# Fires events indicating whether a loading operation is currently happening or not.
+class slender_data.LoadingIndicator
+
+  constructor: ->
+
+    # The number of currently running loading operations.
+    @loader_count = 0
+
+
+  # The different events that this class can fire.
+  @events =
+    AJAX_LOADING: 'AJAX_LOADING'
+    AJAX_LOADED: 'AJAX_LOADED'
+
+
+  # Lets this LoadingIndicator know that another loading operation has started.
+  loading_started: ->
+    @loader_count++
+    if @loader_count == 1
+      $('body').trigger slender_data.AjaxLoader.events.AJAX_LOADING
+
+
+  # Lets this LoadingIndicator know that a loading operation has finished.
+  loading_finished: ->
+    @loader_count--
+    if @loader_count == 0
+      $('body').trigger slender_data.AjaxLoader.events.AJAX_LOADED
+

data/app/assets/javascripts/slender_data/loading_tracker.coffee

@@ -0,0 +1,74 @@
+#= require ../query/single_query
+#= require ../query/multi_query
+
+
+# Tracks which snippets are currently getting loaded,
+# and manages requests for snippet data.
+class sn.LoadingTracker
+
+  constructor: ->
+
+    # Maps currently loading snippets to callbacks waiting for their data.
+    # Key = snippet id, value = array of callbacks
+    @loading_snippets = {}
+
+
+  # Returns whether the snippet with the given id is currently loading.
+  is_loading: (query) ->
+    query = sn.SingleQuery.instancify query
+    console.log "LoadingTracker.is_loading: snippet #{query.id()} loading status: #{@loading_snippets[query.id()]?}"
+    @loading_snippets[query.id()]?
+
+
+  # Returns all ids within the requested ids that are currently loading.
+  matching_loading_ids: (requested_ids) ->
+    _.filter requested_ids, (requested_id) =>
+      @is_loading id: requested_id
+
+
+  # Notifies this LoadingTracker that the given snippet has arrived.
+  snippet_arrived: (snippet) ->
+    console.log "LoadingTracker: received snippet #{snippet.id}"
+
+    # Call the callbacks registered for the loaded snippet.
+    if (callbacks = @loading_snippets[snippet.id])
+      callback() for callback in callbacks
+
+    # Remove the id of the loaded snippet from the loading list.
+    delete @loading_snippets[snippet.id]
+
+
+  # Notifies this LoadingTracker that the given snippets have arrived.
+  snippets_arrived: (snippets) ->
+    console.log "LoadingTracker: received snippets #{(s.id for s in snippets).join '+'}"
+    @snippet_arrived(snippet) for snippet in snippets
+
+
+  # Registers the given snippet as currently loading from the server.
+  start_loading: (query) ->
+    query = sn.SingleQuery.instancify query
+    console.log "LoadingTracker: starting to load #{query.id()}"
+    @loading_snippets[query.id()] or= []
+
+
+  # Registers the given snippets as currently loading from the server.
+  start_loadings: (multi_query) ->
+    multi_query = sn.MultiQuery.instancify multi_query
+    console.log "LoadingTracker: starting to load multiple #{multi_query.ids()}"
+    @start_loading(query) for query in multi_query.transpose()
+
+
+  # Calls the given callback when the snippet with the given id is loaded.
+  wait_for_loading_finished: (query, callback) ->
+    query = sn.SingleQuery.instancify query
+
+    if @is_loading(query)
+      # Snippet is loading --> queue the callback until later.
+      console.log "LoadingTracker.wait_for_loading_finished: snippet #{query.id()} is loading, waiting for it"
+      @loading_snippets[query.id()].push callback
+    else
+      # Snippet is not loading --> return immediately.
+      console.log "LoadingTracker.wait_for_loading_finished: snippet #{query.id()} is not loading"
+      return callback()
+
+

data/app/assets/javascripts/slender_data/parameterizable.coffee

@@ -0,0 +1,50 @@
+# Base class for all classes that are configured by a SlenderData configuration object.
+class slender_data.Parameterizable
+
+  constructor: (params) ->
+
+    # The name of a data entry,
+    # i.e. "user".
+    @entry_name = params.entry_name ? throw new Error('You must provide an entry name')
+
+    # Name of multiple data entries,
+    # i.e. "users".
+    @entries_name = params.entries_name ? "#{@entry_name}s"
+
+    # Name of the id field in entries.
+    @id_name = params.id_name ? 'id'
+
+    # Name of the ids field in entries.
+    @ids_name = params.ids_name ? "#{@id_name}s"
+
+    # The method to use to check whether a given entry is full or partial.
+    @is_full_entry = params.full_entry_checker
+
+    # The class that is used to represent multi-queries.
+    @multi_query_class = params.multi_query_class ? slender_data.MultiQuery
+
+    # The given parameters.
+    @params = params
+
+    # Whether partial entry supported is enabled.
+    @partial_entries = params.partial_entries ? no
+
+    # The class that is used to represent single queries.
+    @single_query_class = params.single_query_class ? slender_data.SingleQuery
+
+    # Name of the version attribute,
+    # i.e. "timestamp".
+    @version_name = params.version_name ? 'version'
+
+    # Whether versioning should be supported or not.
+    @versioning = params.versioning ? no
+
+
+  # Makes sure the given query is indeed a SingleQuery.
+  _querify_single: (query) ->
+    slender_data.querify query, @single_query_class, @params
+
+  # Makes sure the given query is indeed a MultiQuery.
+  _querify_multi: (multi_query) ->
+    slender_data.querify multi_query, @multi_query_class, @params
+