querier-ts 2.0.1 → 2.1.0

package/README.md

@@ -24,30 +24,6 @@ const usersQuery = Query.from<User>(users);
 
 ---
 
-### Getting results
-
-#### `all()`
-
-Returns all results.
-
-#### `first()`
-
-Returns the first result.
-
-#### `last()`
-
-Returns the last result.
-
-#### `count()`
-
-Returns the number of results.
-
-#### `exists()`
-
-Returns a boolean indicating whether any results exist.
-
----
-
 ### Filtering data
 
 #### `where(condition)`
@@ -103,82 +79,48 @@ const filteredUsers = Query.from(users)
 
 ---
 
-### Selecting specific data
+### Selecting data
 
 #### `select(columns)`
 
-Defines which columns should be selected.
-It can be combined with `scalar()`, `column()`, or `values()`.
+Defines which columns should be selected, returning a new query with rows containing only the selected columns.
 
-Accepts either a string (single column) or an array of column names.
+Accepts multiple column names.
 
 ```ts
-.select('id')
+.select('id', 'email')
 ```
 
 ---
 
-#### `scalar()`
-
-Returns the value of the first property of the first result.
-
-```ts
-const firstId = Query.from(users).scalar();
-```
-
-You can combine it with `select()` to retrieve a specific property:
-
-```ts
-const firstEmail = Query.from(users)
-  .select('email')
-  .scalar();
-```
-
-Returns `false` if no value is found.
-
----
-
-#### `column()`
+#### `map(callback)`
 
-Returns the values of the first property from all results by default.
+Transforms each row into a new object using a callback function.
 
-```ts
-const ids = Query.from(users).column();
-```
+Like `select()`, this method is intended for data projection, but it is more flexible and better suited for complex transformations:
 
-You can specify a column:
 
 ```ts
-const emails = Query.from(users).column('email');
+const authorsWithFirstPostQuery = Query.from(authors)
+  .map(({ posts, ...author }) => ({
+    ...author
+    firstPost: posts[0],
+  }));
 ```
 
-Or combine it with `select()`:
+When dealing with simples scenarios, prefer `select()`:
 
 ```ts
-const emails = Query.from(users)
-  .select('email')
-  .column();
-```
-
----
-
-#### `values()`
-
-Returns all results as arrays of values.
-
-```ts
-const data = Query.from(users)
-  .select(['id', 'email'])
-  .values();
-```
-
-Example output:
-
-```ts
-[
-  [1, 'john@icloud.com'],
-  [2, 'mary@gmail.com']
-]
+// ⚠️ More verbose than necessary
+const query = Query.from(users)
+  .map((user) => ({
+    id: user.id,
+    email: user.email,
+  }));
+
+// ✅ More concise and expressive
+const query = Query.from()
+  .select('id', 'email');
 ```
 
 ---
@@ -238,3 +180,100 @@ const secondId = Query.from(users)
 ```
 
 > Passing a non-integer or a negative number will throw an `InvalidArgumentError`.
+
+---
+
+### Getting results
+
+#### `all()`
+
+Returns all results.
+
+---
+
+#### `first()`
+
+Returns the first result.
+
+---
+
+#### `last()`
+
+Returns the last result.
+
+---
+
+#### `count()`
+
+Returns the number of results.
+
+---
+
+#### `exists()`
+
+Returns a boolean indicating whether any results exist.
+
+---
+
+#### `scalar()`
+
+Returns the value of the first property of the first result.
+
+```ts
+const firstId = Query.from(users).scalar();
+```
+
+You can combine it with `select()` to retrieve a specific property:
+
+```ts
+const firstEmail = Query.from(users)
+  .select('email')
+  .scalar();
+```
+
+Returns `false` if no value is found.
+
+---
+
+#### `column()`
+
+Returns the values of the first property from all results by default.
+
+```ts
+const ids = Query.from(users).column();
+```
+
+You can specify a column:
+
+```ts
+const emails = Query.from(users).column('email');
+```
+
+Or combine it with `select()`:
+
+```ts
+const emails = Query.from(users)
+  .select('email')
+  .column();
+```
+
+---
+
+#### `values()`
+
+Returns all results as arrays of values.
+
+```ts
+const data = Query.from(users)
+  .select(['id', 'email'])
+  .values();
+```
+
+Example output:
+
+```ts
+[
+  [1, 'john@icloud.com'],
+  [2, 'mary@gmail.com']
+]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "querier-ts",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Query tool for analysing arrays of objects",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",