api-ape 0.0.0 → 1.0.1

package/server/socket/send.js

@@ -0,0 +1,55 @@
+const jss = require('../../utils/jss')
+
+function checkSocketState(socket) {
+  if (socket.readyState !== socket.OPEN) {
+    switch (socket.readyState) {
+      case socket.CONNECTING:
+        throw "The connection is not yet open"
+        break;
+      case socket.CLOSING:
+        throw "The connection is in theprocess of closing."
+        break;
+      case socket.CLOSED:
+        throw "The connection is closed or couldn't be opened."
+        break;
+    } // END switch 
+    //TODO: remove this socket if closed
+  } // END if
+} // END checkSocketState
+
+module.exports = function sendHandler({ socket, events, hostId }) {
+
+  return function send(queryId, type, data, err) {
+    if (!type && !queryId) {
+      throw new Error("You must pass a type OR a queryId in-order to send messages")
+    }
+    if (!data && !err) {
+      throw new Error("You must pass a data payload OR an error message in-order to send messages")
+    }
+    let onFinish = false
+    if (!queryId) { // dont call onSend as this will be past of the onReceive Flow
+      onFinish = events.onSend(data, type)
+    }
+
+    try {
+      checkSocketState(socket)
+    } catch (err) {
+      if (onFinish) {
+        onFinish(err, false)
+      } else if (queryId) {
+        throw err
+      } else {
+        console.error(err)
+      }
+      return;
+    }
+    if (err) {
+      socket.send(jss.stringify({ err: err.message || err, type, queryId }))
+      if (typeof onFinish === 'function') onFinish(err, true)
+    } else {
+      socket.send(jss.stringify({ data, type, queryId }))
+      if (typeof onFinish === 'function') onFinish(false, data)
+    }
+
+  } // END send
+} //sendHandler

package/server/utils/deepRequire.js

@@ -0,0 +1,45 @@
+if(!global.process){//(!!process && typeof process !== 'object'){
+  throw new Error("deepRequire need to be run on Node server")
+}
+
+var fs = require('fs');
+var path = require('path');
+
+// Return a list of files of the specified fileTypes in the provided dir,
+// with the file path relative to the given dir
+// dir: path of the directory you want to search the files for
+// fileTypes: array of file types you are search files, ex: ['.txt', '.jpg']
+function getFilesFromDir(dir, fileTypes) {
+  var filesToReturn = [];
+  function walkDir(currentPath) {
+    var files = fs.readdirSync(currentPath);
+    for (var i in files) {
+      var curFile = path.join(currentPath, files[i]);
+      if (fs.statSync(curFile).isFile() && fileTypes.indexOf(path.extname(curFile)) != -1) {
+        filesToReturn.push(curFile.replace(dir, ''));
+      } else if (fs.statSync(curFile).isDirectory()) {
+       walkDir(curFile);
+      }
+    }
+  };
+  walkDir(dir);
+  return filesToReturn;
+}
+const re = /(?:\.([^.]+))?$/;
+
+module.exports = function(dirname,selector){
+  selector = selector || ["js"]
+  return getFilesFromDir(dirname, selector.map(ext=>`.${ext}`)).reduce((packages,file) =>{
+
+    if(file === "/index.js")  return packages
+    //if(file[0] !== "/") file = "/"+file;
+
+    const pathParts = file.replace(re.exec(file)[0],"").split("/").slice(1)
+    if(pathParts[pathParts.length-1] === "index")
+    pathParts.pop()
+
+    packages[pathParts.join("/").toLowerCase()] = require(dirname+`/${file}`)
+    return packages;
+  },{});
+
+}

package/server/utils/genId.js

@@ -0,0 +1,24 @@
+function genId(size, range) {
+  
+  size  = size ||  10
+  range = range|| "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+  
+  if ('number' !== typeof size ) {
+    throw new Error("size must be a number")
+  } else if (1 > size) {
+    throw new Error("positive size needed")
+  } else if ('string' !== typeof range ) {
+    throw new Error("range must be a string")
+  } else if (1 > range.length) {
+    throw new Error("range to small")
+  }
+  
+  var id = ""
+  
+  for (var i = 0; i < size; i++) {
+    id += range[~~(Math.random() * range.length)]
+  }
+  return id
+} // END genId
+
+module.exports = genId

package/todo.md

@@ -0,0 +1,85 @@
+# Query System - TODO
+
+A fluent, chainable query API for api-ape with filtering, field selection, and real-time subscriptions.
+
+---
+
+## Client API Design
+```js
+const petsReq = ape.pets.list(data, (item) => shouldSubscribe)
+      petsReq.filter`name ! ${undefined} AND bio.checkin > ${10} OR bio.type = ${"admin"}`
+      petsReq.fields("*", {bio: ["email"]})
+      petsReq.then(pets => ...).catch(err => ...)
+```
+
+---
+
+## Phase 1: Filter Parser
+- [ ] Create `client/utils/filter.js` - tagged template parser
+- [ ] Parse operators: `=`, `!` (not equal), `?` (exists), `>`, `<`
+- [ ] Parse `AND` / `OR` with correct precedence
+- [ ] Support nested paths (e.g., `bio.checkin`, `owner.type`)
+- [ ] Return serializable filter object to send over wire
+
+## Phase 2: Fields Selection  
+- [ ] Parse `fields("*", {relation: ["field1", "field2"]})`
+- [ ] `"*"` = all root-level fields
+- [ ] Object syntax for nested/related field selection
+- [ ] Max depth limit (≤ 4)
+
+## Phase 3: Query Builder (Client)
+- [ ] Refactor `client/index.js` → proper query builder
+- [ ] Chainable `.filter()` and `.fields()` methods
+- [ ] Integrate with existing `connectSocket.js` sender
+- [ ] Send query payload: `{ type, data, filter, fields, subscribe }`
+
+## Phase 4: Subscription Callback
+- [ ] Second arg: `(item) => boolean` subscription predicate
+- [ ] Register listener via `setOnReciver` for matching type
+- [ ] Filter incoming broadcasts client-side with predicate
+
+## Phase 5: Server Query Execution
+- [ ] Parse incoming `filter` object
+- [ ] Apply filter to controller response data
+- [ ] Respect `fields` selection (project/limit returned data)
+- [ ] Track subscribed queryIds for broadcast targeting
+
+## Phase 6: Skip/Have Optimization (Future)
+- [ ] `.dont([id1, id2])` - skip items client already has
+- [ ] Server tracks live refs per client
+- [ ] Only send missing/changed items
+
+---
+
+## Open Questions
+
+### Query Method Semantics
+- `ape.pets.list(null, (pet) => { pet.owner == me })`:
+  - [ ] What does the first argument (`null`) represent? Initial filter data? Query options?
+  - [ ] What does the callback do? Live subscription filter? Server-side predicate?
+
+### Filter Syntax
+- `.filter\`name ! ${undefined} AND owner.checkin > ${10} OR owner.type = ${"nice"}\``:
+  - [ ] Confirm operators: `!` = not equal, `?` = exists, `>` `<` `=` = comparison
+  - [ ] Need additional operators? `>=`, `<=`, `LIKE`, `IN`, `BETWEEN`?
+  - [ ] Should `AND`/`OR` respect standard boolean precedence?
+  - [ ] Should `${10}DaysAgo` be a special relative time syntax?
+
+### Fields Selection
+- `.fields("*", {toys: ["type"]})`:
+  - [ ] `"*"` = all fields at root level?
+  - [ ] Object syntax `{relation: [...]}` for nested/related fields?
+  - [ ] Max depth limit? (code comment says ≤ 4)
+  - [ ] Support exclusion? (e.g., `"-password"`)
+
+### Real-time Subscriptions
+- [ ] How should live updates work? Push on any change to matching items?
+- [ ] Can the subscription filter differ from the initial query filter?
+- [ ] What events trigger updates? Create, Update, Delete?
+- [ ] Broadcast filtering - server-side or client-side predicate eval?
+
+### Additional Features (In Scope?)
+- [ ] Pagination: `.limit()`, `.offset()`, `.cursor()`
+- [ ] Sorting: `.orderBy()`
+- [ ] Aggregations: `.count()`, `.sum()`
+- [ ] Skip/Have optimization: `.dont([ids])` for delta updates

package/utils/jss.js

@@ -0,0 +1,273 @@
+//JsonSuperSet
+
+// TODO: add tests
+// check for any repeated ref not just cyclical references
+// support nasted array a<![,,[D]]>:["a","b",[Date]]
+// support array for the same type a<![*D]>:[Date,Date,Date]
+
+function encode(obj) {
+    const tagLookup = {
+        '[object RegExp]': 'R',
+        '[object Date]': 'D',
+        '[object Error]': 'E',
+        "[object Undefined]": 'U',
+        "[object Map]": 'M',
+        "[object Set]": 'S',
+    };
+    const visited = new WeakMap();
+
+    function encodeValue(value, path = '') {
+        const type = typeof value;
+        const tag = tagLookup[Object.prototype.toString.call(value)];
+        // console.log({tag,value,path})
+        if (tag !== undefined) {
+            if ('D' === tag) return [tag, value.valueOf()];
+            if ('E' === tag) return [tag, [value.name, value.message, value.stack]];
+            if ('R' === tag) return [tag, value.toString()];
+            if ('U' === tag) return [tag, null];
+            if ('S' === tag) return [tag, Array.from(value)];
+            if ('M' === tag) return [tag, Object.fromEntries(value)];
+
+            return [tag, JSON.stringify(value)];
+        } else if (type === 'object' && value !== null) {
+            /*if (value.$ID) {
+              return ['', value.$ID];
+            }*/
+            if (visitedEncode.has(value)) {
+                return ['P', visitedEncode.get(value)];
+            }
+            visitedEncode.set(value, path);
+            const isArray = Array.isArray(value);
+            // keep index with undefined in Array
+            const keys = isArray ? Array.from(Array(value.length).keys()) : Object.keys(value);
+            const result = isArray ? [] : {};
+            const typesFound = [];
+            for (let i = 0; i < keys.length; i++) {
+                const key = keys[i];
+                const [t, v] = encodeValue(value[key], key);
+                // console.log([t, v])
+                if (isArray) {
+                    typesFound.push(t);
+                    result.push(v);
+                    // remove key with undefined from Objects
+                } else if (value[key] !== undefined) {
+                    result[key + (t ? `<!${t}>` : '')] = v;
+                }
+            }
+
+            visited.delete(value);
+            if (isArray && typesFound.find((t) => !!t)) {
+                return [`[${typesFound.join()}]`, result];
+            }
+            return ['', result];
+        } else {
+            return ['', value];
+        }
+    } // END encodeValue
+
+    let keys = [];
+    // console.log(obj)
+    if (Array.isArray(obj)) {
+        keys = Array.from(Array(obj.length).keys())
+    } else {
+        keys = Object.keys(obj);
+    }
+
+    // Track root object to handle self-references
+    const visitedEncode = new WeakMap();
+    visitedEncode.set(obj, []);  // Root path is empty array
+
+    function encodeValueWithVisited(value, path = []) {
+        const type = typeof value;
+        const tag = tagLookup[Object.prototype.toString.call(value)];
+        if (tag !== undefined) {
+            if ('D' === tag) return [tag, value.valueOf()];
+            if ('E' === tag) return [tag, [value.name, value.message, value.stack]];
+            if ('R' === tag) return [tag, value.toString()];
+            if ('U' === tag) return [tag, null];
+            if ('S' === tag) return [tag, Array.from(value)];
+            if ('M' === tag) return [tag, Object.fromEntries(value)];
+            return [tag, JSON.stringify(value)];
+        } else if (type === 'object' && value !== null) {
+            if (visitedEncode.has(value)) {
+                return ['P', visitedEncode.get(value)];  // Return array path
+            }
+            visitedEncode.set(value, path);
+            const isArray = Array.isArray(value);
+            const objKeys = isArray ? Array.from(Array(value.length).keys()) : Object.keys(value);
+            const result = isArray ? [] : {};
+            const typesFound = [];
+            for (let i = 0; i < objKeys.length; i++) {
+                const key = objKeys[i];
+                const [t, v] = encodeValueWithVisited(value[key], [...path, key]);  // Append key to path array
+                if (isArray) {
+                    typesFound.push(t);
+                    result.push(v);
+                } else if (value[key] !== undefined) {
+                    result[key + (t ? `<!${t}>` : '')] = v;
+                }
+            }
+            if (isArray && typesFound.find((t) => !!t)) {
+                return [`[${typesFound.join()}]`, result];
+            }
+            return ['', result];
+        } else {
+            return ['', value];
+        }
+    }
+
+    const result = {};
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        // remove key with undefined from Objects
+        if (obj[key] !== undefined) {
+            const [t, v] = encodeValueWithVisited(obj[key], [key]);  // Start path with single key
+            result[key + (t ? `<!${t}>` : '')] = v;
+        }
+    }
+    return result;
+} // END encode
+
+function stringify(obj) {
+    return JSON.stringify(encode(obj))
+}
+
+
+function parse(encoded) {
+    return decode(JSON.parse(encoded))
+}
+
+function decode(data) {
+    const result = {};
+    const pointers2Res = [];
+    const tagLookup = {
+        R: (s) => new RegExp(s),
+        D: (n) => new Date(n),
+        P: function (sourceToPointAt, replaceAtThisPlace) {
+            // Both paths are now arrays
+            pointers2Res.push([sourceToPointAt, replaceAtThisPlace]);
+            return null;  // Placeholder, will be replaced by changeAttributeReference
+        },
+        E: ([name, message, stack]) => {
+            let err;
+            try {
+                err = new global[name](message);
+                if (err instanceof Error) err.stack = stack;
+                else throw {};
+            } catch (e) {
+                err = new Error(message);
+                err.name = name;
+                err.stack = stack;
+            }
+            return err;
+        },
+        U: () => undefined,
+        S: (a) => new Set(a),
+        M: (o) => new Map(Object.entries(o))
+    };
+    const visited = new Map();
+
+    function decodeValue(name, tag, val) {
+        // this is now an array path
+        const currentPath = Array.isArray(this) ? this : [];
+
+        if (tag in tagLookup) {
+            return tagLookup[tag](val, currentPath);
+        } else if (Array.isArray(val)) {
+            if (tag && tag.startsWith('[')) {
+                const typeTags = tag.slice(1, -1).split(',');
+                const res = [];
+                for (let i = 0; i < val.length; i++) {
+                    // Pass path with array index appended
+                    const itemPath = [...currentPath, i];
+                    const decodedValue = decodeValue.call(
+                        itemPath,
+                        i.toString(),
+                        typeTags[i],
+                        val[i]
+                    );
+                    res.push(decodedValue);
+                }
+                return res;
+            } else {
+                const res = [];
+                for (let i = 0; i < val.length; i++) {
+                    const decodedValue = decodeValue.call([...currentPath, i], '', '', val[i]);
+                    res.push(decodedValue);
+                }
+                return res;
+            }
+        } else if ('object' === typeof val && val !== null) {
+            if (visited.has(val)) {
+                return visited.get(val);
+            }
+            visited.set(val, {});
+            const res = {};
+            for (const key in val) {
+                const [nam, t] = parseKeyWithTags(key);
+                const decodedValue = decodeValue.call(
+                    [...currentPath, nam],
+                    nam,
+                    t,
+                    val[key]
+                );
+                res[nam] = decodedValue;
+            }
+            visited.set(val, res);
+            return res;
+        } else {
+            return val;
+        }
+    } // END decodeValue
+
+    function parseKeyWithTags(key) {
+        const match = key.match(/(.+)(<!(.)>)/);
+        if (match) {
+            return [match[1], match[3]];
+        }
+        // Try multi-character tags like array types [,D,]
+        const multiMatch = key.match(/(.+)(<!!(.+)>)/);
+        if (multiMatch) {
+            return [multiMatch[1], multiMatch[3]];
+        }
+        // Also handle array type tags that start with [
+        const arrayMatch = key.match(/(.+)(<!\[(.*)>)/);
+        if (arrayMatch) {
+            return [arrayMatch[1], '[' + arrayMatch[3]];
+        }
+        return [key, undefined];
+    } // END parseKeyWithTags
+
+    for (const key in data) {
+        const [name, tag] = parseKeyWithTags(key);
+        // Start with path containing just the key name
+        result[name] = decodeValue.call([name], name, tag, data[key]);
+    }
+    pointers2Res.forEach(changeAttributeReference.bind(null, result));
+    return result;
+} // END decode
+
+function changeAttributeReference(obj, [refPath, attrPath]) {
+    // refPath and attrPath are now arrays, no splitting needed
+    const refKeys = refPath || [];
+    const attrKeys = attrPath || [];
+
+    // Get the reference target by traversing refPath
+    let ref = obj;
+    for (let i = 0; i < refKeys.length; i++) {
+        ref = ref[refKeys[i]];
+    }
+
+    // Get the parent of the attribute to set
+    let attr = obj;
+    for (let i = 0; i < attrKeys.length - 1; i++) {
+        attr = attr[attrKeys[i]];
+    }
+
+    // Set the attribute to point to the reference
+    attr[attrKeys[attrKeys.length - 1]] = ref;
+    return obj;
+} // END changeAttributeReference
+
+
+module.exports = { parse, stringify, encode, decode };