objql-object-query-language v3.2.0

ObjQL

ObjQL is a helpful library allowing you to select particular entries from a collection, i.e., an array of objects. An example of code using that is below:

const collection = [
	{name: 'Adam', age: 18},
	{name: 'Adam', age: 42},
	{name: 'Mark', age: 19},
	{name: 'Joseph', age: 34},
	{name: 'Jack', age: 42},
	{name: 'Michael', age: 24}
];

const results = ObjQL
	.from(collection)
	.select('*')
	.where({
		age: 18
	})
	.sort('name')
	.limit(2,3);

// => [{name: 'Adam', age: 18}]

Currently, the select() method only supports '*' as a first parameter.
It will change in one of the future releases.

Methods must be called in the following order: from(), select(), where(), sort() and limit(). The last two may be omitted, however.

Installation

npm i objql-object-query-language

Compound fields

Items in a collection can have additional fields added. To do so, use a callback as a second parameter of the select() method.

.select('*', item => ({
	desc: `${item.name} being ${item.age} having a ${item.extra}`
}))

Dependencies of compound fields

When some field doesn't have some property, a compound field may have a value that contains undefined, what might not be intended.

As a third parameter of the select() method, you can pass an array of strings - property names that all must be present in item to add compound properties.

.select('*', item => ({
	desc: `${item.name} being ${item.age} having a ${item.extra}`
}), ['name', 'age', 'extra'])

Shortcuts for Functions

Functions

General

The match() matcher

A callback passed to the match() matcher can accept up to 4 parameters:

• value of a field in a current record
• entire current record
• index of the current record in the entire collection
• entire collection

// get items followed by another item whose
// `result` property is greater than or equal to
// the `result` property of the current item

ObjQL.from(collection)
.select('*')
.where({
	name: ObjQL.match((name, item, idx, coll) => {
		return (
			coll[idx+1] &&
			coll[idx+1].result >= item.result
		);
	})
})

Strings

Date

There are functions checking date that can be represented by:

• a particular value (e.g., month(4) to match April)
• an instance of the Date()
• a timestamp (a number of milliseconds that have passed from 01.01.1970 00:00:00)
• a string in one of the following formats: YYYY-MM-DD HH:mm:ss.uuu DD.MM.YYYY HH:mm:ss.uuu * MM/DD/YYYY HH:mm:ss.uuu
• the ObjQL.CURRENT constant

When it comes to the latest three, the following parts are optional: entire time part (HH:mm:ss.uuu), seconds with milliseconds (ss.uuu) and milliseconds (uuu).

The dateFormat parameter in the date() method can consist of the following parts: YYYY - full year, MM - month, DD - day, HH - hour, mm - minute, ss - second, uuu - millisecond.

Examples of matching date

• match entries where the start_date field is date whose month is April

where({
	start_date: ObjQL.month(4)
})

• match entries where the start_date field is date whose day is 14th and month is February

where({
	start_date: ObjQL.date('DD.MM', '14.02')
})

Note that the second parameter may be the standard date. In such a case, it does not have to match a format given as the first parameter. Elements from the first parameter will be used to compare dates:

where({
	// pass entire date
	// but only compare day and month
	start_date: ObjQL.date('DD.MM', '2020-02-14 15:45:30')
})

• match entries where the event_date field is date whose week day is Friday, Saturday or Sunday

where({
	event_date: ObjQL.weekDay([5, 7])
})

Array of Numbers

Example ranges:

• count('a', [1, 4]) - a number of occurencies of a >= 1 and <= 4
• count('a', [2, null]) - a number of occurencies of a >= 2
• count('a', [null, 5]) - a number of occurencies of a <= 5

How do min()/max() work?

const collection = ObjQL.from([
	{name: 'John', marks: [3, 4, 6]},
	{name: 'Mark', marks: [2, 3, 5]}
]);



const result = collection.select('*').where({
	marks: ObjQL.min(2)
});
// only Mark has been matched
// John has not as his minimum value is 3

const result2 = collection.select('*').where({
	marks: ObjQL.min([2, 4])
});
// both Mark and John have been matched
// given minimum value is from the range 2-4



const result3 = collection.select('*').where({
	marks: ObjQL.min([null, 2])
});
// only Mark has been matched
// minimum value must be less or equal to 2 [null, 2]

const result4 = collection.select('*').where({
	marks: ObjQL.min([2, null])
});
// both Mark and John have been matched
// minimum value must be greater or equal to 2 [2, null]

Objects

Types