@sincpro/criteria-react 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,10 +19,10 @@ clean it up on unmount.
19
19
  import { useReading } from "@sincpro/criteria-react";
20
20
  import { criteria } from "@sincpro/criteria";
21
21
 
22
- function DatasetList({ resource, where }: Props) {
22
+ function DatasetList({ resource, selection }: Props) {
23
23
  const { rows, status, hasMore, more } = useReading(
24
24
  resource,
25
- criteria<Dataset>().where(where).limit(50),
25
+ criteria<Dataset>().selection(selection).limit(50),
26
26
  );
27
27
 
28
28
  if (status === "loading") return <Spinner />;
@@ -73,22 +73,22 @@ site. A small custom hook is the natural shape, not a HOC — nothing here needs
73
73
  component to do this:
74
74
 
75
75
  ```tsx
76
- import { criteria, merge, plain, where } from "@sincpro/criteria";
76
+ import { criteria, merge, plain, selection } from "@sincpro/criteria";
77
77
  import { useReading } from "@sincpro/criteria-react";
78
78
 
79
79
  function usePermissionedAccounts(resource: Resource<Account>, typed: Expression<Account>) {
80
- const permission = criteria<Account>().where(
81
- where.any(["region", "=", "north"], ["owner", "=", useCurrentUser()]),
80
+ const permission = criteria<Account>().selection(
81
+ selection.any(["region", "=", "north"], ["owner", "=", useCurrentUser()]),
82
82
  );
83
- const asked = merge(plain(permission), plain(criteria<Account>().where(typed)));
83
+ const asked = merge(plain(permission), plain(criteria<Account>().selection(typed)));
84
84
  return useReading(resource, asked);
85
85
  }
86
86
  ```
87
87
 
88
88
  `asked` is what actually reaches the network — the user's filter narrows the permission, it
89
- can never widen past it, because `where` always merges by AND. See the core README's "The law
89
+ can never widen past it, because `selection` always merges by AND. See the core README's "The law
90
90
  for merging two of them" for what merge does with the rest of a criteria (order, pagination,
91
- grouping), not just `where`.
91
+ grouping), not just `selection`. `.selection()` is the method that writes that field.
92
92
 
93
93
  ## Development
94
94
 
package/dist/buckets.d.ts CHANGED
@@ -44,19 +44,19 @@ export interface UseBucketsResult<T> extends BucketsState<T> {
44
44
  * @example
45
45
  * // complex: two grouping levels, two measures, a filter over the groups themselves,
46
46
  * // group-count paging AND row-count paging, and following one bucket's own cursor further.
47
- * import { resumingFrom, where } from "@sincpro/criteria";
47
+ * import { resumingFrom, selection } from "@sincpro/criteria";
48
48
  *
49
49
  * function HighVolumeProducers({ resource }: Props) {
50
50
  * const tree = useBuckets(
51
51
  * resource,
52
52
  * criteria<Dataset>()
53
- * .where(
53
+ * .selection(
54
54
  * ["row_count", ">", 50],
55
- * where.any(
56
- * where.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
55
+ * selection.any(
56
+ * selection.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
57
57
  * ["registered_at", ">=", "2026-03-01T00:00:00.000Z"],
58
58
  * ),
59
- * where.negate(["name", "like", "draft"]),
59
+ * selection.negate(["name", "like", "draft"]),
60
60
  * )
61
61
  * .groupBy("encoding", "producer_id")
62
62
  * .measures({ total_rows: measure.sum("row_count") })
package/dist/buckets.js CHANGED
@@ -36,19 +36,19 @@ import { useEffect, useMemo, useSyncExternalStore } from "react";
36
36
  * @example
37
37
  * // complex: two grouping levels, two measures, a filter over the groups themselves,
38
38
  * // group-count paging AND row-count paging, and following one bucket's own cursor further.
39
- * import { resumingFrom, where } from "@sincpro/criteria";
39
+ * import { resumingFrom, selection } from "@sincpro/criteria";
40
40
  *
41
41
  * function HighVolumeProducers({ resource }: Props) {
42
42
  * const tree = useBuckets(
43
43
  * resource,
44
44
  * criteria<Dataset>()
45
- * .where(
45
+ * .selection(
46
46
  * ["row_count", ">", 50],
47
- * where.any(
48
- * where.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
47
+ * selection.any(
48
+ * selection.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
49
49
  * ["registered_at", ">=", "2026-03-01T00:00:00.000Z"],
50
50
  * ),
51
- * where.negate(["name", "like", "draft"]),
51
+ * selection.negate(["name", "like", "draft"]),
52
52
  * )
53
53
  * .groupBy("encoding", "producer_id")
54
54
  * .measures({ total_rows: measure.sum("row_count") })
package/dist/reading.d.ts CHANGED
@@ -32,7 +32,7 @@ export interface UseReadingResult<T> extends Omit<ReadingState<T>, "more"> {
32
32
  * function DatasetList({ resource }: Props) {
33
33
  * const { rows, status, hasMore, more } = useReading(
34
34
  * resource,
35
- * criteria<Dataset>().where(["encoding", "=", "utf-8"]).limit(50),
35
+ * criteria<Dataset>().selection(["encoding", "=", "utf-8"]).limit(50),
36
36
  * );
37
37
  * if (status === "loading") return <Spinner />;
38
38
  * return <List rows={rows} onEndReached={more} hasMore={hasMore} />;
@@ -40,11 +40,11 @@ export interface UseReadingResult<T> extends Omit<ReadingState<T>, "more"> {
40
40
  *
41
41
  * @example
42
42
  * // medium: a saved permission merged with what the user typed, refined on every keystroke
43
- * import { merge, plain, where } from "@sincpro/criteria";
43
+ * import { merge, plain, selection } from "@sincpro/criteria";
44
44
  *
45
45
  * function DatasetSearch({ resource, typed }: Props) {
46
- * const permission = criteria<Dataset>().where(where.any(["region", "=", "north"]));
47
- * const asked = merge(plain(permission), plain(criteria<Dataset>().where(typed)));
46
+ * const permission = criteria<Dataset>().selection(selection.any(["region", "=", "north"]));
47
+ * const asked = merge(plain(permission), plain(criteria<Dataset>().selection(typed)));
48
48
  * const { rows, refine } = useReading(resource, asked);
49
49
  * // call refine(nextCriteria) again whenever `typed` changes
50
50
  * return <List rows={rows} />;
@@ -54,14 +54,14 @@ export interface UseReadingResult<T> extends Omit<ReadingState<T>, "more"> {
54
54
  * // complex: AND(A, B, OR(AND(C, D), E), NOT(F)) — three real levels of nesting. useReading
55
55
  * // only needs the finished criteria; grouping is {@link useBuckets}'s job, not this one's.
56
56
  * function RecentRawUploads({ resource }: Props) {
57
- * const q = criteria<Dataset>().where(
57
+ * const q = criteria<Dataset>().selection(
58
58
  * ["row_count", ">", 50],
59
59
  * ["encoding", "!=", "latin-1"],
60
- * where.any(
61
- * where.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
60
+ * selection.any(
61
+ * selection.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
62
62
  * ["registered_at", ">=", "2026-03-01T00:00:00.000Z"],
63
63
  * ),
64
- * where.negate(["name", "like", "draft"]),
64
+ * selection.negate(["name", "like", "draft"]),
65
65
  * );
66
66
  * const { rows } = useReading(resource, q);
67
67
  * return <List rows={rows} />;
package/dist/reading.js CHANGED
@@ -14,7 +14,7 @@ import { useEffect, useMemo, useSyncExternalStore } from "react";
14
14
  * function DatasetList({ resource }: Props) {
15
15
  * const { rows, status, hasMore, more } = useReading(
16
16
  * resource,
17
- * criteria<Dataset>().where(["encoding", "=", "utf-8"]).limit(50),
17
+ * criteria<Dataset>().selection(["encoding", "=", "utf-8"]).limit(50),
18
18
  * );
19
19
  * if (status === "loading") return <Spinner />;
20
20
  * return <List rows={rows} onEndReached={more} hasMore={hasMore} />;
@@ -22,11 +22,11 @@ import { useEffect, useMemo, useSyncExternalStore } from "react";
22
22
  *
23
23
  * @example
24
24
  * // medium: a saved permission merged with what the user typed, refined on every keystroke
25
- * import { merge, plain, where } from "@sincpro/criteria";
25
+ * import { merge, plain, selection } from "@sincpro/criteria";
26
26
  *
27
27
  * function DatasetSearch({ resource, typed }: Props) {
28
- * const permission = criteria<Dataset>().where(where.any(["region", "=", "north"]));
29
- * const asked = merge(plain(permission), plain(criteria<Dataset>().where(typed)));
28
+ * const permission = criteria<Dataset>().selection(selection.any(["region", "=", "north"]));
29
+ * const asked = merge(plain(permission), plain(criteria<Dataset>().selection(typed)));
30
30
  * const { rows, refine } = useReading(resource, asked);
31
31
  * // call refine(nextCriteria) again whenever `typed` changes
32
32
  * return <List rows={rows} />;
@@ -36,14 +36,14 @@ import { useEffect, useMemo, useSyncExternalStore } from "react";
36
36
  * // complex: AND(A, B, OR(AND(C, D), E), NOT(F)) — three real levels of nesting. useReading
37
37
  * // only needs the finished criteria; grouping is {@link useBuckets}'s job, not this one's.
38
38
  * function RecentRawUploads({ resource }: Props) {
39
- * const q = criteria<Dataset>().where(
39
+ * const q = criteria<Dataset>().selection(
40
40
  * ["row_count", ">", 50],
41
41
  * ["encoding", "!=", "latin-1"],
42
- * where.any(
43
- * where.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
42
+ * selection.any(
43
+ * selection.all(["tags", "contains", "raw"], ["producer_id", "!=", null]),
44
44
  * ["registered_at", ">=", "2026-03-01T00:00:00.000Z"],
45
45
  * ),
46
- * where.negate(["name", "like", "draft"]),
46
+ * selection.negate(["name", "like", "draft"]),
47
47
  * );
48
48
  * const { rows } = useReading(resource, q);
49
49
  * return <List rows={rows} />;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sincpro/criteria-react",
3
- "version": "1.0.0",
3
+ "version": "2.0.0",
4
4
  "description": "React hooks over @sincpro/criteria's Reading and Buckets, plus a query-key helper for wiring a resource into an existing cache (react-query, …). See docs/DESIGN.md at the repo root for why this is a separate package.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",