can-connect behavior notes.md

can-connect behavior changes

• create behavior bundles

  • adds multiple behaviors at once (as required)

    • concerned that adding behaviors as required will be complicated since we may not just require the presence of a particular attribute, we'll require that particular attribute as implemented by specific behavior

      • e.g real-time doesn't just require just any implementation of the instance callbacks, it will have undefined functionality if it doesn't get the callbacks as implemented by constructor/callbacks-once instead of the constructor/constructor implementation of the callbacks

        • if we start requiring specific behaviors rather than just the interface how do we make these requirements while still allowing users to replace those individual behaviors?

        • this also complicates automatic ordering of behaviors, how do we know if a behavior that requires instance callbacks should be ordered so that it gets the can/map implementation or the constructor/callbacks-once implementation?

        • could be resolved by ordering behaviors by interfaces names.

          • eg. naming the interface implemented by constructor/callbacks-once different than the callbacks supplied by constructor/constructor even though they're the same "shape"

  • makes configuration easier for major use cases

  • ensures required dependencies are present

  • types:

    • basic data

      • data/url
      • data/parse
      • data/callbacks

    • type instantiation

      • constructor
      • constructor/store
      • can/map
      • can/merge

    • caching

      • fall-through-cache
      • data/callbacks-cache
      • one of:
        • data/localstorage-cache
        • data/memory-cache

    • others, just add their dependencies if not already present rather that grouped out of convienence

      • combine requests
      • real time updating

• documentation improvements

  • top-level documentation should be guides oriented around functionality / usage rather than individual behavior docs

  • guides:

    • basic connection configuration
    • data type instantation (using CanJS types)
    • caching
    • handling object references
    • real time updates
    • combine request
    • worker
    • usage with React

  • lower-level API docs should still be per-behavior of course, but API docs don't make it easy to see how behaviors should be composed and commonly configured. it's probably ineffective to try to make them do so at anything more than a cursory level

  • lower-level API docs should include an index page that shows a directed graph of our behaviors ordered by their dependencies

  • constructor/callbacks-once

    • currently describes impelementing "data" callbacks though it actually implements "instance" callbacks

• insertion commands

// inserts a behavior on the connection above/below the specified behaviours. allows specifying an insertion at the topmost or bottommost matching location. the default is topmost.

var exampleBehaviorInterface = {
	name: 'ExampleBehaviorInterface',
	properties: ['test', 'example'] 
}

connection.insert(behavior, {
	'above': [cacheBehaviorInterface],
    'below': [mapBehaviorInterface],
    'position': ('first' | 'last')
})

// behavior target is either a name string or target object reference
connection.replace(behaviorTarget, behavior);