Command List

Below is a list of commands that can be used in jLINQ. This list is still in progress so there are many commands that are not listed yet.

If you are unsure why the field name is optional on some commands, you may need to read the article about Chaining Commands to understand how some commands work.

String Comparisons

.contains(["field"], "value")
returns jLinq object
Checks if the field contains the value. Is case sensitive unless you use the .ignoreCase() command before the .contains command.

var results = jLinq.from(records)
  .ignoreCase()
  .contains("name","b")
  .select();


.startsWith(["field"], "value")
returns jLinq object
Checks if the field starts with the value. Is case sensitive unless you use the .ignoreCase() command before the .startsWith command.

var results = jLinq.from(records)
  .ignoreCase()
  .startsWith("name","b")
  .select();


.endsWith(["field"], "value")
returns jLinq object
Checks if the field ends with the value. Is case sensitive unless you use the .ignoreCase() command before the .endsWith command.

var results = jLinq.from(records)
  .ignoreCase()
  .endsWith("name","b")
  .select();


.match(["field"], "value"|RegularExpression)
returns jLinq object
Checks if the field matches the regular expression provided. You can use a string or an actual Regular Expression. Is case sensitive unless you use the .ignoreCase() command before the .match command.

var results = jLinq.from(records)
  .ignoreCase()
  .match("name","ad|br|cl|de") //string
  .or(/ad|br|cl|de/) //or a regular expression
  .select();

Case Flags

.ignoreCase()
returns jLinq object
Tells all further string comparisons to ignore case. This works for parameters that are strings and Regular Expression objects.

var results = jLinq.from(records)
  .ignoreCase()
  .contains("name","b") //matches b or B
  .select();


.useCase()
returns jLinq object
Tells all further string comparisons to consider the case. This works for parameters that are strings and Regular Expression objects.

var results = jLinq.from(records)
  .useCase() //by default this is already on
  .contains("name","b") //only matches b, will not match B
  .select();

Operators

.or(["field"],[multi-parameters-depending-on-previous-command])
returns jLinq object
Marks the next command to use the OR operator instead of the default AND. You can optionally provide the name of the field and value, and if a command has already been used, it will be repeated again.

var results = jLinq.from(records)
  .startsWith("name","a")
  .or("name", "b") //you can provide both field and value
  .or("c") // or just the value since the field is know
  .or().startsWith("d") // or you can use or by itself then use another command
  .or().endsWith("e")
  .select();



.and(["field"],[multi-parameters-depending-on-previous-command])
returns jLinq object
Marks the next command to use the AND operator. *AND is the default operator so you don't have to use this command. You can optionally provide the name of the field and value, and if a command has already been used, it will be repeated again.

//AND is implied after each command so the following query is unlikely to ever be used.
var results = jLinq.from(records)
  .startsWith("name","a")
  .and("name", "b") //you can provide both field and value
  .and("c") // or just the value since the field is know
  .and().startsWith("d") // or you can use _or_ by itself then use another command
  .and().endsWith("e")
  .select();


.not(["field"],[parameters-depending-on-previous-command])
returns jLinq object
Marks that the next comparison should be evaluated as NOT. You can use command chaining with this command. Using this command twice in a row, .not().not() creates a double negative.

var results = jLinq.from(records)
  .startsWith("name","a").not("name", "A") // starts with 'a' not 'A'
  .not().not().startsWith("b") // double negative, matches names that start with b
  .not().greater("age", 30) // ages less than 30
  .select();


.orNot(["field"],[parameters-depending-on-previous-command])
returns jLinq object
Shortcut command for using .or().not(). You can use command chaining with this command.

var results = jLinq.from(records)
  .not().equals("age",10)
  .orNot(20)
  .orNot(30)
  .select();


.andNot(["field"],[parameters-depending-on-previous-command])
returns jLinq object
Shortcut command for using .and().not() or even more simply .not(). You can use command chaining with this command.

var results = jLinq.from(records)
  .not().equals("age",10)
  .andNot(20)
  .andNot(30)
  .select();

Boolean Comparisons

.is(["field"])
returns jLinq object
Checks if the field is true. While this command can remember a previous field, it is unlikely that it will ever be used that way.

var results = jLinq.from(records)
  .is("isAdmin")
  .select();


.isNot(["field"])
returns jLinq object
Checks if the field is false. While this command can remember a previous field, it is unlikely that it will ever be used that way.

var results = jLinq.from(records)
  .isNot("isAdmin")
  .select();

Numeric Comparisons

Future versions will support Dates, but as of 2.0.0, only numbers will work

.greater(["field"], number)
returns jLinq object
Checks if the field is greater than the value provided.

var results = jLinq.from(records)
  .greater("age",10)
  .select();


.less(["field"], number)
returns jLinq object
Checks if the field is less than the value provided.

var results = jLinq.from(records)
  .less("age",30)
  .select();


.greaterEquals(["field"], number)
returns jLinq object
Checks if the field is greater or equal to the value provided.

var results = jLinq.from(records)
  .greaterEquals("age",10)
  .select();


.lessEquals(["field"], number)
returns jLinq object
Checks if the field is less than or equal to the value provided.

var results = jLinq.from(records)
  .lessEquals("age",30)
  .select();


.between(["field"], low-number, high-number)
returns jLinq object
Checks if the field is between the two values provided.

var results = jLinq.from(records)
  .between("age",10,40)
  .select();


.betweenEquals(["field"], low-number, high-number)
returns jLinq object
Checks if the field is between or equal to the two values provided.

var results = jLinq.from(records)
  .betweenEquals("age",10,40)
  .select();

General Comparisons

.equals(["field"], any-value)
returns jLinq object
Checks if the field is equal to the value provided. This value will check the type provided and compare the values. Is case sensitive if comparing strings unless you use the .ignoreCase() command before the .equals command.

var results = jLinq.from(records)
  .equals("age",25)
  .or("name","john")
  .select();


.where(["field"], "string-query"|where-function)
returns jLinq object
Allows for custom query writing. For details on how to use this command, see the article about UsingTheWhereCommand (not yet written_)

var results = jLinq.from(records)
  .where("rec.name == 'john'") //string, record must be named 'rec'
  .where(function(r) { //or a delegate
    return r.name == "john";
  })
  .select();

Complex Comparisons

.combine(sub-query-function)
returns jLinq object
Allows you to create a section of a query that is evaluated separately than the rest of the query. This is used when an OR comparison contains an AND comparison. This command seems a little strange at first, but will make sense after using it a couple times. A second article will be written to explain this better.

//example of a query that fails
//the intended comparison is
//(user.admin || (!user.admin && user.age > 50))
var results = jLinq.from(records)
  .is("admin")
  .orNot("admin")
  .greater("age",50)
  .select(); //evaluates as (user.admin || !user.admin && user.age > 50) - no parens

//The correct way to write the query below, using the combine command
//(user.admin || (!user.admin && user.age > 50))
var results = jLinq.from(records)
  .is("admin")
  .combine(function(q) {
    return q.isNot("admin")
      .greater("age",50)
  })
  .select();

Ordering

.orderBy("field", ["d|a"])
returns jLinq object
Orders the records by the field selected. You can use more than one ordering command and they will each be evaluated. Ascending order is implied but you can use "d", "desc", "descending", "a", "asc", "ascending" to specify the direction. Is case sensitive if comparing strings unless you use the .ignoreCase() command before the .orderBy command.

var results = jLinq.from(records)
  .orderBy("name")
  .orderBy("age")
  .select();

Array Comparisons

.each("field", subquery-function)
returns jLinq object
Used to perform a comparison on each entry inside of an array. The delegate should accept a single jLinq object as a parameter. With that jLinq object you create a sub query that does not return any records. The delegate should return the parameter that was passed in.

var results = jLinq.from(records)
  .ignoreCase()
  .each("permissions", function(r) {
    //ignoreCase is carried into a sub query automatically
    return r.contains("delete").or("write"); //return the passed in jLinq object
  })
  .select();


.isEmpty("field")
returns jLinq object
Checks to see if an array is empty or not. If the array is empty then it will match as true for the query.

var results = jLinq.from(records)
  .isEmpty("permissions") //return true if the array is empty
  .select();


.hasValues("field")
returns jLinq object
Checks to see if an array has any values. If the array has values then it will match as true for the query.

var results = jLinq.from(records)
  .hasValue("permissions") //return true if the array has values
  .select();

Selection Methods

.select([selection-function],[invert-bool])
returns Array
Selects the records that match the query. The query is evaluated at this point. You can provide a delegate to change the information that is selected. You can also invert the selection which will return all records that do not match the query.

var results = jLinq.from(records)
  .greater("age", 30)
  .select(); //selects the records as is

var moreResults = jLinq.from(records)
  .is("isAdmin")
  .select(function(rec) {
    //selects a custom format for the records
    return {
      fullName:rec.first + " " + rec.last
    };
  });

//to invert a selection
var eventMoreResults = jLinq.from(records)
  .startsWith("J")
  .select(null, true);


.update(edit-function)
returns object { changed:[array], unchanged:[array] }
Acts mostly like the .select command, but the edit delegate is required and also returns an object that contains two arrays; one containing changed records and the other with the unchanged records.

var results = jLinq.from(records)
  .greater("age", 25)
  .update(function(rec) {
    rec.age += 10;
    return rec;
  })
  .updated; // array of ages greater than 25 that have had 10 added to them

.update(edit-function)
returns object { removed:[array], remaining:[array] }
Acts mostly like the .select command, but the edit delegate is required and also returns an object that contains two arrays; one containing changed records and the other with the unchanged records.

var results = jLinq.from(records)
  .less("age", 25)
  .remove()
  .remaining; // array of ages greater than 25 - .removed contains all of the matches


.hasMatch()
returns boolean
Returns if any matches are located when executing the query.

var hasAtLeastOneAdmin = jLinq.from(records)
  .is("admin")
  .hasMatch();


.withEach(with-each-function)
returns jLinq object
Similar to the update method where the delegate is required, but instead of returning any results, it returns the jLinq object. This is useful for displaying data as part of a query instead of selecting an array and then looping through it.

document.body.innerHTML += "People starting with 'M'<br/>";
jLinq.from(records)
  .ignoreCase()
  .startsWith("name","m")
  .withEach(function(rec) {
    document.body.innerHTML += rec.name + "<br />";
  });
  //.select() - you could continue a query here.

Other Result Methods

.count()
returns integer
Returns the total count of the matches for the query.

var total = jLinq.from(records)
  .is("admin")
  .count();

.first()
returns record-type or null
Returns the first result in a query. If there are no results then a null is returned instead.

var firstAdmin = jLinq.from(users)
  .is("admin")
  .first();

.firstOrDefault(default-type)
returns record-type or default-type
Returns the first result in a query. If there are no results then the default type is returned instead.

var locationName = jLinq.from(location)
  .is("defaultLocation")
  .firstOrDefault({name:"No Default Location Selected"})
  .name;


.last()
returns record-type or null
Returns the last result in a query. If there are no results then a null is returned instead.

var lastLoginUser = jLinq.from(users)
  .orderBy("lastLogin") // you could use descending order then first
  .last();

. lastOrDefault(default-type)
returns record-type or default-type
Returns the last result in a query. If there are no results then the default type is returned instead.

var oldestUser = jLinq.from(users)
  .orderBy("age") // you could use descending order then first
  .lastOrDefault({name:"No Users Found"})
  .name;


.at(integer-index)
returns record-type or null
Returns the record at the index provided. If nothing is there, or it is out of range, a null is returned instead.

var secondUser = jLinq.from(users)
  .orderBy("name")
  .at(1);


.skip(integer-index)
returns jLinq object
Instructs the query that the first x number of records should be skipped when a selection method is used. If the skip selects past the end of the records then an empty array is returned instead.

var usersAfterFifth = jLinq.from(users)
  .skip(5)
  .select();

//Multiple skips increment the value
var laterUsers = jLinq.from(users)
  .skip(5) // skip 5
  .skip(5) // skip 10
  .skip(5) //skip 15... why you would ever do this, I don't know...
  .select();


.take(integer-index)
returns Array
Selects the number of records provided. If .skip() was used before, that number of records will be skipped before returning the results. You do not need to use .skip() before you use .take().

var someThreeUsers = jLinq.from(users)
  .skip(5)
  .take(3); //array of 3 or less records, but skipping the first 5.

var firstThreeUsers = jLinq.from(users)
  .take(3); //array of 3 or less records from the start.

Other commands

.join(array, "alias", "primary-key", ["foreign-key"])
returns jLinq object
Used to populate relationships from one array to another. If no foreign-key is provided, then the primary-key is assumed to be the correct value. The alias is the name to call the new property when it is attached.

var locations = [
  {id:1, name:"Home Office", number:"555.1212" },
  {id:2, name:"Downtown Office", number:"555.3434" }
];

var results = jLinq.from(users)
  .join(locations, "location", "locationId", "id")
  .select(function(rec) {
    return {
      userName: rec.username,
      officeName: rec.location.name //location is now a property
    };
  });


.showQuery(query-function)
returns jLinq object
This command is useful to debug any problems you might have with a query. When a query is executed the final string is compared using the .eval() command; .showQuery() will display the query string that is used.

var results = jLinq.from(users)
  .ignoreCase()
  .startsWith("name", "J").or("k")
  .showQuery(function(q) {
    alert(q) // displays '((rec.name.toString().match(/J/i))||(rec.name.toString().match(/k/i)))'
  })
  .select(); // still returns array of results

More Commands To Be Listed

View the source code to see other commands. More commands will be listed soon.

Last edited Apr 9, 2009 at 3:28 AM by hboss, version 13

Comments

No comments yet.