Proposal for new can-set API (Rought Draft)

can-set-api.js

var set = require('can-set');

// The current API
var algebra = new set.Algebra(
  // specify the unique identifier on data
  set.props.id("_id"),
  // specify that completed can be true, false or undefined
  set.props.boolean("retired"),
  // specify properties that define pagination
  set.props.rangeInclusive("start","end"),
  // specify the property that controls sorting
  set.props.sort("orderBy"),
})



/**
 * fromSchema {Function} from the 'can-set/from-schema' module
 * `fromSchema` iterates the schema's keys and passes each key into the
 * schema function that it was given.  The return value would be passed
 * to `new set.Algebra(schema)`
 */
export function fromSchema (schema, aliases, responseSchemas) {
  const fullSchema = {}

  Object.keys(simpleSchema).forEach(key => {
    const propFn = schema[key]
    fullSchema[key] = propFn(key)
  })
  return schema // where from here?
}

/**
 * id {Function} from the `can-set/types` module
 * This shows a high level example of what one
 */
export function id (prop) {
  // Might have some special id handling logic, here

  return function (value) {
    checkNestedProps(prop, value)
    // Check id stuff
  }
}


export function checkNestedProps (value) {
  // Check for special nested properties
  const props = [$in, $nin, $lt, $lte, $gt, $gte, $ne]
  if (isObject(value)) {
    props.forEach(prop => {
      if (value[prop]) {
        // Do something with the prop.
      }
    })
  }
}


/**
 * This is an example of how the new API would be consumed.
 */

// These are the main schema functions.
import { id, string, equal, enumerable, deepEqual, boolean, rangeStart, rangeEnd, sort, or, select } from 'can-set/types'
// These are schema functions for handling responses
import { data, limit, skip, total } from 'can-set/response-types' // definitely not final
import fromSchema from 'can-set/from-schema'

var algebra = new set.Algebra(fromSchema({
    _id: id,
    firstName: string,
    lastName: string, // can be implicit
    applesOrOranges: enumerable(['Apples', 'Oranges']),
    retired: boolean,
    $sort: sort,
    $skip: rangeStart,
    $limit: rangeEnd,
    $select: select,
    // total: 67, // Do we need to account for the response total for rangeEnd?
    $or: or, // What would this actually be?
    favoriteColor: string
  // Optionally alias the special nested query props
  }, {
    $in: 'in',
    $nin: 'notIn',
    $lt: 'lessThan',
    $lte: 'lessThanOrEqual',
    $gt: 'greaterThan',
    $gte: 'greaterThanOrEqual',
    $ne: 'notEqualTo'
  // We need a way to tell the algebra about the response.
  }, {
    itemResponse: { data },
    listResponse: {
      data,  // results
      skip,  // works with rangeStart
      limit, // works with rangeEnd
      total  // some utility to work with rangeEnd, maybe?
    }
  // And we potentially want headers
  }, {
    Authorization
  })
);


var query = {
  _id: '208hvl2l9ehbecoi3o',
  lastName: 'Fadeev',
  retired: true,
  $sort: {
    firstName: 1
  },
  $skip: 5,
  $limit: 10,
  $select: ['field1', 'field2'],
  favoriteColor: {
    $in: ['red', 'blue'],
  },
  numberOfChildren: {
    $nin: [4, 6],
  },
  dateBoughtFirstCar: {
    $lt: new Date('2010-01-05'),
  },
  numberOfPaintingsOwned: {
    $lte: 6,
  },
  createdAt: {
    $gt: 0,
  },
  lastSeen: {
    $gte: 1,
  },
  archived: {
    $ne: null
  },
  $or: [
    { archived: { $ne: true } },
    { roomId: 2 }
  ]
}