@osdk/react 0.9.0-beta.7 → 0.9.0-beta.8

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.
Files changed (8) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/build/browser/new/useOsdkAggregation.js.map +1 -1
  3. package/build/cjs/public/experimental.d.cts +1 -1
  4. package/build/esm/new/useOsdkAggregation.js.map +1 -1
  5. package/build/types/new/useOsdkAggregation.d.ts +1 -1
  6. package/build/types/new/useOsdkAggregation.d.ts.map +1 -1
  7. package/docs/advanced-queries.md +28 -22
  8. package/package.json +5 -5
package/CHANGELOG.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # @osdkkit/react
2
2
 
3
+ ## 0.9.0-beta.8
4
+
5
+ ### Minor Changes
6
+
7
+ - 74e3ba7: Preserve aggregate option literal types in useOsdkAggregation using const type parameter
8
+
9
+ ### Patch Changes
10
+
11
+ - Updated dependencies [3fc5fe6]
12
+ - Updated dependencies [bb9d25c]
13
+ - @osdk/client@2.7.0-beta.12
14
+ - @osdk/api@2.7.0-beta.12
15
+
3
16
  ## 0.9.0-beta.7
4
17
 
5
18
  ### Minor Changes
package/build/browser/new/useOsdkAggregation.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"useOsdkAggregation.js","names":["React","makeExternalStore","OsdkContext2","useOsdkAggregation","type","where","withProperties","aggregate","dedupeIntervalMs","observableClient","useContext","canonWhere","canonicalizeWhereClause","stableWithProperties","useMemo","JSON","stringify","stableAggregate","subscribe","getSnapShot","observer","observeAggregation","dedupeInterval","process","env","NODE_ENV","apiName","payload","useSyncExternalStore","error","status","Error","refetch","useCallback","invalidateObjectType","data","result","isLoading"],"sources":["useOsdkAggregation.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n AggregateOpts,\n AggregationsResults,\n DerivedProperty,\n ObjectOrInterfaceDefinition,\n WhereClause,\n} from \"@osdk/api\";\nimport type { ObserveAggregationArgs } from \"@osdk/client/unstable-do-not-use\";\nimport React from \"react\";\nimport { makeExternalStore } from \"./makeExternalStore.js\";\nimport { OsdkContext2 } from \"./OsdkContext2.js\";\nimport type { InferRdpTypes } from \"./types.js\";\n\nexport interface UseOsdkAggregationOptions<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n WithProps extends DerivedProperty.Clause<T> | undefined = undefined,\n> {\n /**\n * Standard OSDK Where clause to filter objects before aggregation\n */\n where?: WhereClause<T, InferRdpTypes<T, WithProps>>;\n\n /**\n * Define derived properties (RDPs) to be computed server-side.\n * The derived properties can be used in the where clause and aggregation groupBy/select.\n */\n withProperties?: WithProps;\n\n /**\n * Aggregation options including groupBy and select\n */\n aggregate: A;\n\n /**\n * The number of milliseconds to wait after the last observed aggregation change.\n *\n * Two uses of `useOsdkAggregation` with the same parameters will only trigger one\n * network request if the second is within `dedupeIntervalMs`.\n */\n dedupeIntervalMs?: number;\n}\n\nexport interface UseOsdkAggregationResult<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n> {\n data: AggregationsResults<T, A> | undefined;\n isLoading: boolean;\n error: Error | undefined;\n refetch: () => void;\n}\n\ndeclare const process: {\n env: {\n NODE_ENV: \"development\" | \"production\";\n };\n};\n\n/**\n * React hook for performing aggregations on OSDK object sets.\n *\n * Executes server-side aggregations with groupBy and metric calculations on filtered object sets.\n * Supports runtime derived properties and where clauses.\n *\n * @param type - The object or interface type to aggregate\n * @param options - Aggregation configuration including where clause, aggregation spec, and optional derived properties\n * @returns Object containing aggregation results, loading state, error state, and refetch function\n *\n * @example\n * ```tsx\n * const { data, isLoading, error } = useOsdkAggregation(Employee, {\n * where: { department: \"Engineering\" },\n * aggregate: {\n * groupBy: { department: \"exact\" },\n * select: {\n * avgSalary: { $avg: \"salary\" },\n * count: { $count: {} }\n * }\n * }\n * });\n * ```\n */\nexport function useOsdkAggregation<\n Q extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<Q>,\n WP extends DerivedProperty.Clause<Q> | undefined = undefined,\n>(\n type: Q,\n {\n where = {},\n withProperties,\n aggregate,\n dedupeIntervalMs,\n }: UseOsdkAggregationOptions<Q, A, WP>,\n): UseOsdkAggregationResult<Q, A> {\n const { observableClient } = React.useContext(OsdkContext2);\n\n const canonWhere = observableClient.canonicalizeWhereClause<Q>(where ?? {});\n\n const stableWithProperties = React.useMemo(\n () => withProperties,\n [JSON.stringify(withProperties)],\n );\n\n const stableAggregate = React.useMemo(\n () => aggregate,\n [JSON.stringify(aggregate)],\n );\n\n const { subscribe, getSnapShot } = React.useMemo(\n () =>\n makeExternalStore<ObserveAggregationArgs<Q, A>>(\n (observer) =>\n observableClient.observeAggregation(\n {\n type: type,\n where: canonWhere,\n withProperties: stableWithProperties,\n aggregate: stableAggregate,\n dedupeInterval: dedupeIntervalMs ?? 2_000,\n },\n observer,\n ),\n process.env.NODE_ENV !== \"production\"\n ? `aggregation ${type.apiName} ${JSON.stringify(canonWhere)}`\n : void 0,\n ),\n [\n observableClient,\n type.apiName,\n type.type,\n canonWhere,\n stableWithProperties,\n stableAggregate,\n dedupeIntervalMs,\n ],\n );\n\n const payload = React.useSyncExternalStore(subscribe, getSnapShot);\n\n let error: Error | undefined;\n if (payload && \"error\" in payload && payload.error) {\n error = payload.error;\n } else if (payload?.status === \"error\") {\n error = new Error(\"Failed to execute aggregation\");\n }\n\n const refetch = React.useCallback(async () => {\n await observableClient.invalidateObjectType(type.apiName);\n }, [observableClient, type.apiName]);\n\n return {\n data: payload?.result as AggregationsResults<Q, A> | undefined,\n isLoading: payload?.status === \"loading\" || payload?.status === \"init\"\n || !payload,\n error,\n refetch,\n };\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA,OAAOA,KAAK,MAAM,OAAO;AACzB,SAASC,iBAAiB,QAAQ,wBAAwB;AAC1D,SAASC,YAAY,QAAQ,mBAAmB;AAiDhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAKhCC,IAAO,EACP;EACEC,KAAK,GAAG,CAAC,CAAC;EACVC,cAAc;EACdC,SAAS;EACTC;AACmC,CAAC,EACN;EAChC,MAAM;IAAEC;EAAiB,CAAC,GAAGT,KAAK,CAACU,UAAU,CAACR,YAAY,CAAC;EAE3D,MAAMS,UAAU,GAAGF,gBAAgB,CAACG,uBAAuB,CAAIP,KAAK,IAAI,CAAC,CAAC,CAAC;EAE3E,MAAMQ,oBAAoB,GAAGb,KAAK,CAACc,OAAO,CACxC,MAAMR,cAAc,EACpB,CAACS,IAAI,CAACC,SAAS,CAACV,cAAc,CAAC,CACjC,CAAC;EAED,MAAMW,eAAe,GAAGjB,KAAK,CAACc,OAAO,CACnC,MAAMP,SAAS,EACf,CAACQ,IAAI,CAACC,SAAS,CAACT,SAAS,CAAC,CAC5B,CAAC;EAED,MAAM;IAAEW,SAAS;IAAEC;EAAY,CAAC,GAAGnB,KAAK,CAACc,OAAO,CAC9C,MACEb,iBAAiB,CACdmB,QAAQ,IACPX,gBAAgB,CAACY,kBAAkB,CACjC;IACEjB,IAAI,EAAEA,IAAI;IACVC,KAAK,EAAEM,UAAU;IACjBL,cAAc,EAAEO,oBAAoB;IACpCN,SAAS,EAAEU,eAAe;IAC1BK,cAAc,EAAEd,gBAAgB,IAAI;EACtC,CAAC,EACDY,QACF,CAAC,EACHG,OAAO,CAACC,GAAG,CAACC,QAAQ,KAAK,YAAY,GACjC,eAAerB,IAAI,CAACsB,OAAO,IAAIX,IAAI,CAACC,SAAS,CAACL,UAAU,CAAC,EAAE,GAC3D,KAAK,CACX,CAAC,EACH,CACEF,gBAAgB,EAChBL,IAAI,CAACsB,OAAO,EACZtB,IAAI,CAACA,IAAI,EACTO,UAAU,EACVE,oBAAoB,EACpBI,eAAe,EACfT,gBAAgB,CAEpB,CAAC;EAED,MAAMmB,OAAO,GAAG3B,KAAK,CAAC4B,oBAAoB,CAACV,SAAS,EAAEC,WAAW,CAAC;EAElE,IAAIU,KAAwB;EAC5B,IAAIF,OAAO,IAAI,OAAO,IAAIA,OAAO,IAAIA,OAAO,CAACE,KAAK,EAAE;IAClDA,KAAK,GAAGF,OAAO,CAACE,KAAK;EACvB,CAAC,MAAM,IAAIF,OAAO,EAAEG,MAAM,KAAK,OAAO,EAAE;IACtCD,KAAK,GAAG,IAAIE,KAAK,CAAC,+BAA+B,CAAC;EACpD;EAEA,MAAMC,OAAO,GAAGhC,KAAK,CAACiC,WAAW,CAAC,YAAY;IAC5C,MAAMxB,gBAAgB,CAACyB,oBAAoB,CAAC9B,IAAI,CAACsB,OAAO,CAAC;EAC3D,CAAC,EAAE,CAACjB,gBAAgB,EAAEL,IAAI,CAACsB,OAAO,CAAC,CAAC;EAEpC,OAAO;IACLS,IAAI,EAAER,OAAO,EAAES,MAA+C;IAC9DC,SAAS,EAAEV,OAAO,EAAEG,MAAM,KAAK,SAAS,IAAIH,OAAO,EAAEG,MAAM,KAAK,MAAM,IACjE,CAACH,OAAO;IACbE,KAAK;IACLG;EACF,CAAC;AACH","ignoreList":[]}
1
+ {"version":3,"file":"useOsdkAggregation.js","names":["React","makeExternalStore","OsdkContext2","useOsdkAggregation","type","where","withProperties","aggregate","dedupeIntervalMs","observableClient","useContext","canonWhere","canonicalizeWhereClause","stableWithProperties","useMemo","JSON","stringify","stableAggregate","subscribe","getSnapShot","observer","observeAggregation","dedupeInterval","process","env","NODE_ENV","apiName","payload","useSyncExternalStore","error","status","Error","refetch","useCallback","invalidateObjectType","data","result","isLoading"],"sources":["useOsdkAggregation.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n AggregateOpts,\n AggregationsResults,\n DerivedProperty,\n ObjectOrInterfaceDefinition,\n WhereClause,\n} from \"@osdk/api\";\nimport type { ObserveAggregationArgs } from \"@osdk/client/unstable-do-not-use\";\nimport React from \"react\";\nimport { makeExternalStore } from \"./makeExternalStore.js\";\nimport { OsdkContext2 } from \"./OsdkContext2.js\";\nimport type { InferRdpTypes } from \"./types.js\";\n\nexport interface UseOsdkAggregationOptions<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n WithProps extends DerivedProperty.Clause<T> | undefined = undefined,\n> {\n /**\n * Standard OSDK Where clause to filter objects before aggregation\n */\n where?: WhereClause<T, InferRdpTypes<T, WithProps>>;\n\n /**\n * Define derived properties (RDPs) to be computed server-side.\n * The derived properties can be used in the where clause and aggregation groupBy/select.\n */\n withProperties?: WithProps;\n\n /**\n * Aggregation options including groupBy and select\n */\n aggregate: A;\n\n /**\n * The number of milliseconds to wait after the last observed aggregation change.\n *\n * Two uses of `useOsdkAggregation` with the same parameters will only trigger one\n * network request if the second is within `dedupeIntervalMs`.\n */\n dedupeIntervalMs?: number;\n}\n\nexport interface UseOsdkAggregationResult<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n> {\n data: AggregationsResults<T, A> | undefined;\n isLoading: boolean;\n error: Error | undefined;\n refetch: () => void;\n}\n\ndeclare const process: {\n env: {\n NODE_ENV: \"development\" | \"production\";\n };\n};\n\n/**\n * React hook for performing aggregations on OSDK object sets.\n *\n * Executes server-side aggregations with groupBy and metric calculations on filtered object sets.\n * Supports runtime derived properties and where clauses.\n *\n * @param type - The object or interface type to aggregate\n * @param options - Aggregation configuration including where clause, aggregation spec, and optional derived properties\n * @returns Object containing aggregation results, loading state, error state, and refetch function\n *\n * @example\n * ```tsx\n * const { data, isLoading, error } = useOsdkAggregation(Employee, {\n * where: { department: \"Engineering\" },\n * aggregate: {\n * groupBy: { department: \"exact\" },\n * select: {\n * avgSalary: { $avg: \"salary\" },\n * count: { $count: {} }\n * }\n * }\n * });\n * ```\n */\nexport function useOsdkAggregation<\n Q extends ObjectOrInterfaceDefinition,\n const A extends AggregateOpts<Q>,\n WP extends DerivedProperty.Clause<Q> | undefined = undefined,\n>(\n type: Q,\n {\n where = {},\n withProperties,\n aggregate,\n dedupeIntervalMs,\n }: UseOsdkAggregationOptions<Q, A, WP>,\n): UseOsdkAggregationResult<Q, A> {\n const { observableClient } = React.useContext(OsdkContext2);\n\n const canonWhere = observableClient.canonicalizeWhereClause<Q>(where ?? {});\n\n const stableWithProperties = React.useMemo(\n () => withProperties,\n [JSON.stringify(withProperties)],\n );\n\n const stableAggregate = React.useMemo(\n () => aggregate,\n [JSON.stringify(aggregate)],\n );\n\n const { subscribe, getSnapShot } = React.useMemo(\n () =>\n makeExternalStore<ObserveAggregationArgs<Q, A>>(\n (observer) =>\n observableClient.observeAggregation(\n {\n type: type,\n where: canonWhere,\n withProperties: stableWithProperties,\n aggregate: stableAggregate,\n dedupeInterval: dedupeIntervalMs ?? 2_000,\n },\n observer,\n ),\n process.env.NODE_ENV !== \"production\"\n ? `aggregation ${type.apiName} ${JSON.stringify(canonWhere)}`\n : void 0,\n ),\n [\n observableClient,\n type.apiName,\n type.type,\n canonWhere,\n stableWithProperties,\n stableAggregate,\n dedupeIntervalMs,\n ],\n );\n\n const payload = React.useSyncExternalStore(subscribe, getSnapShot);\n\n let error: Error | undefined;\n if (payload && \"error\" in payload && payload.error) {\n error = payload.error;\n } else if (payload?.status === \"error\") {\n error = new Error(\"Failed to execute aggregation\");\n }\n\n const refetch = React.useCallback(async () => {\n await observableClient.invalidateObjectType(type.apiName);\n }, [observableClient, type.apiName]);\n\n return {\n data: payload?.result as AggregationsResults<Q, A> | undefined,\n isLoading: payload?.status === \"loading\" || payload?.status === \"init\"\n || !payload,\n error,\n refetch,\n };\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA,OAAOA,KAAK,MAAM,OAAO;AACzB,SAASC,iBAAiB,QAAQ,wBAAwB;AAC1D,SAASC,YAAY,QAAQ,mBAAmB;AAiDhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAKhCC,IAAO,EACP;EACEC,KAAK,GAAG,CAAC,CAAC;EACVC,cAAc;EACdC,SAAS;EACTC;AACmC,CAAC,EACN;EAChC,MAAM;IAAEC;EAAiB,CAAC,GAAGT,KAAK,CAACU,UAAU,CAACR,YAAY,CAAC;EAE3D,MAAMS,UAAU,GAAGF,gBAAgB,CAACG,uBAAuB,CAAIP,KAAK,IAAI,CAAC,CAAC,CAAC;EAE3E,MAAMQ,oBAAoB,GAAGb,KAAK,CAACc,OAAO,CACxC,MAAMR,cAAc,EACpB,CAACS,IAAI,CAACC,SAAS,CAACV,cAAc,CAAC,CACjC,CAAC;EAED,MAAMW,eAAe,GAAGjB,KAAK,CAACc,OAAO,CACnC,MAAMP,SAAS,EACf,CAACQ,IAAI,CAACC,SAAS,CAACT,SAAS,CAAC,CAC5B,CAAC;EAED,MAAM;IAAEW,SAAS;IAAEC;EAAY,CAAC,GAAGnB,KAAK,CAACc,OAAO,CAC9C,MACEb,iBAAiB,CACdmB,QAAQ,IACPX,gBAAgB,CAACY,kBAAkB,CACjC;IACEjB,IAAI,EAAEA,IAAI;IACVC,KAAK,EAAEM,UAAU;IACjBL,cAAc,EAAEO,oBAAoB;IACpCN,SAAS,EAAEU,eAAe;IAC1BK,cAAc,EAAEd,gBAAgB,IAAI;EACtC,CAAC,EACDY,QACF,CAAC,EACHG,OAAO,CAACC,GAAG,CAACC,QAAQ,KAAK,YAAY,GACjC,eAAerB,IAAI,CAACsB,OAAO,IAAIX,IAAI,CAACC,SAAS,CAACL,UAAU,CAAC,EAAE,GAC3D,KAAK,CACX,CAAC,EACH,CACEF,gBAAgB,EAChBL,IAAI,CAACsB,OAAO,EACZtB,IAAI,CAACA,IAAI,EACTO,UAAU,EACVE,oBAAoB,EACpBI,eAAe,EACfT,gBAAgB,CAEpB,CAAC;EAED,MAAMmB,OAAO,GAAG3B,KAAK,CAAC4B,oBAAoB,CAACV,SAAS,EAAEC,WAAW,CAAC;EAElE,IAAIU,KAAwB;EAC5B,IAAIF,OAAO,IAAI,OAAO,IAAIA,OAAO,IAAIA,OAAO,CAACE,KAAK,EAAE;IAClDA,KAAK,GAAGF,OAAO,CAACE,KAAK;EACvB,CAAC,MAAM,IAAIF,OAAO,EAAEG,MAAM,KAAK,OAAO,EAAE;IACtCD,KAAK,GAAG,IAAIE,KAAK,CAAC,+BAA+B,CAAC;EACpD;EAEA,MAAMC,OAAO,GAAGhC,KAAK,CAACiC,WAAW,CAAC,YAAY;IAC5C,MAAMxB,gBAAgB,CAACyB,oBAAoB,CAAC9B,IAAI,CAACsB,OAAO,CAAC;EAC3D,CAAC,EAAE,CAACjB,gBAAgB,EAAEL,IAAI,CAACsB,OAAO,CAAC,CAAC;EAEpC,OAAO;IACLS,IAAI,EAAER,OAAO,EAAES,MAA+C;IAC9DC,SAAS,EAAEV,OAAO,EAAEG,MAAM,KAAK,SAAS,IAAIH,OAAO,EAAEG,MAAM,KAAK,MAAM,IACjE,CAACH,OAAO;IACbE,KAAK;IACLG;EACF,CAAC;AACH","ignoreList":[]}
package/build/cjs/public/experimental.d.cts CHANGED
@@ -388,7 +388,7 @@ interface UseOsdkAggregationResult<T extends ObjectOrInterfaceDefinition, A exte
388
388
  * });
389
389
  * ```
390
390
  */
391
- declare function useOsdkAggregation<Q extends ObjectOrInterfaceDefinition, A extends AggregateOpts<Q>, WP extends DerivedProperty.Clause<Q> | undefined = undefined>(type: Q, { where, withProperties, aggregate, dedupeIntervalMs, }: UseOsdkAggregationOptions<Q, A, WP>): UseOsdkAggregationResult<Q, A>;
391
+ declare function useOsdkAggregation<Q extends ObjectOrInterfaceDefinition, const A extends AggregateOpts<Q>, WP extends DerivedProperty.Clause<Q> | undefined = undefined>(type: Q, { where, withProperties, aggregate, dedupeIntervalMs, }: UseOsdkAggregationOptions<Q, A, WP>): UseOsdkAggregationResult<Q, A>;
392
392
 
393
393
  interface UseOsdkFunctionOptions<Q extends QueryDefinition<unknown>> {
394
394
  /**
package/build/esm/new/useOsdkAggregation.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"useOsdkAggregation.js","names":["React","makeExternalStore","OsdkContext2","useOsdkAggregation","type","where","withProperties","aggregate","dedupeIntervalMs","observableClient","useContext","canonWhere","canonicalizeWhereClause","stableWithProperties","useMemo","JSON","stringify","stableAggregate","subscribe","getSnapShot","observer","observeAggregation","dedupeInterval","process","env","NODE_ENV","apiName","payload","useSyncExternalStore","error","status","Error","refetch","useCallback","invalidateObjectType","data","result","isLoading"],"sources":["useOsdkAggregation.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n AggregateOpts,\n AggregationsResults,\n DerivedProperty,\n ObjectOrInterfaceDefinition,\n WhereClause,\n} from \"@osdk/api\";\nimport type { ObserveAggregationArgs } from \"@osdk/client/unstable-do-not-use\";\nimport React from \"react\";\nimport { makeExternalStore } from \"./makeExternalStore.js\";\nimport { OsdkContext2 } from \"./OsdkContext2.js\";\nimport type { InferRdpTypes } from \"./types.js\";\n\nexport interface UseOsdkAggregationOptions<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n WithProps extends DerivedProperty.Clause<T> | undefined = undefined,\n> {\n /**\n * Standard OSDK Where clause to filter objects before aggregation\n */\n where?: WhereClause<T, InferRdpTypes<T, WithProps>>;\n\n /**\n * Define derived properties (RDPs) to be computed server-side.\n * The derived properties can be used in the where clause and aggregation groupBy/select.\n */\n withProperties?: WithProps;\n\n /**\n * Aggregation options including groupBy and select\n */\n aggregate: A;\n\n /**\n * The number of milliseconds to wait after the last observed aggregation change.\n *\n * Two uses of `useOsdkAggregation` with the same parameters will only trigger one\n * network request if the second is within `dedupeIntervalMs`.\n */\n dedupeIntervalMs?: number;\n}\n\nexport interface UseOsdkAggregationResult<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n> {\n data: AggregationsResults<T, A> | undefined;\n isLoading: boolean;\n error: Error | undefined;\n refetch: () => void;\n}\n\ndeclare const process: {\n env: {\n NODE_ENV: \"development\" | \"production\";\n };\n};\n\n/**\n * React hook for performing aggregations on OSDK object sets.\n *\n * Executes server-side aggregations with groupBy and metric calculations on filtered object sets.\n * Supports runtime derived properties and where clauses.\n *\n * @param type - The object or interface type to aggregate\n * @param options - Aggregation configuration including where clause, aggregation spec, and optional derived properties\n * @returns Object containing aggregation results, loading state, error state, and refetch function\n *\n * @example\n * ```tsx\n * const { data, isLoading, error } = useOsdkAggregation(Employee, {\n * where: { department: \"Engineering\" },\n * aggregate: {\n * groupBy: { department: \"exact\" },\n * select: {\n * avgSalary: { $avg: \"salary\" },\n * count: { $count: {} }\n * }\n * }\n * });\n * ```\n */\nexport function useOsdkAggregation<\n Q extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<Q>,\n WP extends DerivedProperty.Clause<Q> | undefined = undefined,\n>(\n type: Q,\n {\n where = {},\n withProperties,\n aggregate,\n dedupeIntervalMs,\n }: UseOsdkAggregationOptions<Q, A, WP>,\n): UseOsdkAggregationResult<Q, A> {\n const { observableClient } = React.useContext(OsdkContext2);\n\n const canonWhere = observableClient.canonicalizeWhereClause<Q>(where ?? {});\n\n const stableWithProperties = React.useMemo(\n () => withProperties,\n [JSON.stringify(withProperties)],\n );\n\n const stableAggregate = React.useMemo(\n () => aggregate,\n [JSON.stringify(aggregate)],\n );\n\n const { subscribe, getSnapShot } = React.useMemo(\n () =>\n makeExternalStore<ObserveAggregationArgs<Q, A>>(\n (observer) =>\n observableClient.observeAggregation(\n {\n type: type,\n where: canonWhere,\n withProperties: stableWithProperties,\n aggregate: stableAggregate,\n dedupeInterval: dedupeIntervalMs ?? 2_000,\n },\n observer,\n ),\n process.env.NODE_ENV !== \"production\"\n ? `aggregation ${type.apiName} ${JSON.stringify(canonWhere)}`\n : void 0,\n ),\n [\n observableClient,\n type.apiName,\n type.type,\n canonWhere,\n stableWithProperties,\n stableAggregate,\n dedupeIntervalMs,\n ],\n );\n\n const payload = React.useSyncExternalStore(subscribe, getSnapShot);\n\n let error: Error | undefined;\n if (payload && \"error\" in payload && payload.error) {\n error = payload.error;\n } else if (payload?.status === \"error\") {\n error = new Error(\"Failed to execute aggregation\");\n }\n\n const refetch = React.useCallback(async () => {\n await observableClient.invalidateObjectType(type.apiName);\n }, [observableClient, type.apiName]);\n\n return {\n data: payload?.result as AggregationsResults<Q, A> | undefined,\n isLoading: payload?.status === \"loading\" || payload?.status === \"init\"\n || !payload,\n error,\n refetch,\n };\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA,OAAOA,KAAK,MAAM,OAAO;AACzB,SAASC,iBAAiB,QAAQ,wBAAwB;AAC1D,SAASC,YAAY,QAAQ,mBAAmB;AAiDhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAKhCC,IAAO,EACP;EACEC,KAAK,GAAG,CAAC,CAAC;EACVC,cAAc;EACdC,SAAS;EACTC;AACmC,CAAC,EACN;EAChC,MAAM;IAAEC;EAAiB,CAAC,GAAGT,KAAK,CAACU,UAAU,CAACR,YAAY,CAAC;EAE3D,MAAMS,UAAU,GAAGF,gBAAgB,CAACG,uBAAuB,CAAIP,KAAK,IAAI,CAAC,CAAC,CAAC;EAE3E,MAAMQ,oBAAoB,GAAGb,KAAK,CAACc,OAAO,CACxC,MAAMR,cAAc,EACpB,CAACS,IAAI,CAACC,SAAS,CAACV,cAAc,CAAC,CACjC,CAAC;EAED,MAAMW,eAAe,GAAGjB,KAAK,CAACc,OAAO,CACnC,MAAMP,SAAS,EACf,CAACQ,IAAI,CAACC,SAAS,CAACT,SAAS,CAAC,CAC5B,CAAC;EAED,MAAM;IAAEW,SAAS;IAAEC;EAAY,CAAC,GAAGnB,KAAK,CAACc,OAAO,CAC9C,MACEb,iBAAiB,CACdmB,QAAQ,IACPX,gBAAgB,CAACY,kBAAkB,CACjC;IACEjB,IAAI,EAAEA,IAAI;IACVC,KAAK,EAAEM,UAAU;IACjBL,cAAc,EAAEO,oBAAoB;IACpCN,SAAS,EAAEU,eAAe;IAC1BK,cAAc,EAAEd,gBAAgB,IAAI;EACtC,CAAC,EACDY,QACF,CAAC,EACHG,OAAO,CAACC,GAAG,CAACC,QAAQ,KAAK,YAAY,GACjC,eAAerB,IAAI,CAACsB,OAAO,IAAIX,IAAI,CAACC,SAAS,CAACL,UAAU,CAAC,EAAE,GAC3D,KAAK,CACX,CAAC,EACH,CACEF,gBAAgB,EAChBL,IAAI,CAACsB,OAAO,EACZtB,IAAI,CAACA,IAAI,EACTO,UAAU,EACVE,oBAAoB,EACpBI,eAAe,EACfT,gBAAgB,CAEpB,CAAC;EAED,MAAMmB,OAAO,GAAG3B,KAAK,CAAC4B,oBAAoB,CAACV,SAAS,EAAEC,WAAW,CAAC;EAElE,IAAIU,KAAwB;EAC5B,IAAIF,OAAO,IAAI,OAAO,IAAIA,OAAO,IAAIA,OAAO,CAACE,KAAK,EAAE;IAClDA,KAAK,GAAGF,OAAO,CAACE,KAAK;EACvB,CAAC,MAAM,IAAIF,OAAO,EAAEG,MAAM,KAAK,OAAO,EAAE;IACtCD,KAAK,GAAG,IAAIE,KAAK,CAAC,+BAA+B,CAAC;EACpD;EAEA,MAAMC,OAAO,GAAGhC,KAAK,CAACiC,WAAW,CAAC,YAAY;IAC5C,MAAMxB,gBAAgB,CAACyB,oBAAoB,CAAC9B,IAAI,CAACsB,OAAO,CAAC;EAC3D,CAAC,EAAE,CAACjB,gBAAgB,EAAEL,IAAI,CAACsB,OAAO,CAAC,CAAC;EAEpC,OAAO;IACLS,IAAI,EAAER,OAAO,EAAES,MAA+C;IAC9DC,SAAS,EAAEV,OAAO,EAAEG,MAAM,KAAK,SAAS,IAAIH,OAAO,EAAEG,MAAM,KAAK,MAAM,IACjE,CAACH,OAAO;IACbE,KAAK;IACLG;EACF,CAAC;AACH","ignoreList":[]}
1
+ {"version":3,"file":"useOsdkAggregation.js","names":["React","makeExternalStore","OsdkContext2","useOsdkAggregation","type","where","withProperties","aggregate","dedupeIntervalMs","observableClient","useContext","canonWhere","canonicalizeWhereClause","stableWithProperties","useMemo","JSON","stringify","stableAggregate","subscribe","getSnapShot","observer","observeAggregation","dedupeInterval","process","env","NODE_ENV","apiName","payload","useSyncExternalStore","error","status","Error","refetch","useCallback","invalidateObjectType","data","result","isLoading"],"sources":["useOsdkAggregation.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n AggregateOpts,\n AggregationsResults,\n DerivedProperty,\n ObjectOrInterfaceDefinition,\n WhereClause,\n} from \"@osdk/api\";\nimport type { ObserveAggregationArgs } from \"@osdk/client/unstable-do-not-use\";\nimport React from \"react\";\nimport { makeExternalStore } from \"./makeExternalStore.js\";\nimport { OsdkContext2 } from \"./OsdkContext2.js\";\nimport type { InferRdpTypes } from \"./types.js\";\n\nexport interface UseOsdkAggregationOptions<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n WithProps extends DerivedProperty.Clause<T> | undefined = undefined,\n> {\n /**\n * Standard OSDK Where clause to filter objects before aggregation\n */\n where?: WhereClause<T, InferRdpTypes<T, WithProps>>;\n\n /**\n * Define derived properties (RDPs) to be computed server-side.\n * The derived properties can be used in the where clause and aggregation groupBy/select.\n */\n withProperties?: WithProps;\n\n /**\n * Aggregation options including groupBy and select\n */\n aggregate: A;\n\n /**\n * The number of milliseconds to wait after the last observed aggregation change.\n *\n * Two uses of `useOsdkAggregation` with the same parameters will only trigger one\n * network request if the second is within `dedupeIntervalMs`.\n */\n dedupeIntervalMs?: number;\n}\n\nexport interface UseOsdkAggregationResult<\n T extends ObjectOrInterfaceDefinition,\n A extends AggregateOpts<T>,\n> {\n data: AggregationsResults<T, A> | undefined;\n isLoading: boolean;\n error: Error | undefined;\n refetch: () => void;\n}\n\ndeclare const process: {\n env: {\n NODE_ENV: \"development\" | \"production\";\n };\n};\n\n/**\n * React hook for performing aggregations on OSDK object sets.\n *\n * Executes server-side aggregations with groupBy and metric calculations on filtered object sets.\n * Supports runtime derived properties and where clauses.\n *\n * @param type - The object or interface type to aggregate\n * @param options - Aggregation configuration including where clause, aggregation spec, and optional derived properties\n * @returns Object containing aggregation results, loading state, error state, and refetch function\n *\n * @example\n * ```tsx\n * const { data, isLoading, error } = useOsdkAggregation(Employee, {\n * where: { department: \"Engineering\" },\n * aggregate: {\n * groupBy: { department: \"exact\" },\n * select: {\n * avgSalary: { $avg: \"salary\" },\n * count: { $count: {} }\n * }\n * }\n * });\n * ```\n */\nexport function useOsdkAggregation<\n Q extends ObjectOrInterfaceDefinition,\n const A extends AggregateOpts<Q>,\n WP extends DerivedProperty.Clause<Q> | undefined = undefined,\n>(\n type: Q,\n {\n where = {},\n withProperties,\n aggregate,\n dedupeIntervalMs,\n }: UseOsdkAggregationOptions<Q, A, WP>,\n): UseOsdkAggregationResult<Q, A> {\n const { observableClient } = React.useContext(OsdkContext2);\n\n const canonWhere = observableClient.canonicalizeWhereClause<Q>(where ?? {});\n\n const stableWithProperties = React.useMemo(\n () => withProperties,\n [JSON.stringify(withProperties)],\n );\n\n const stableAggregate = React.useMemo(\n () => aggregate,\n [JSON.stringify(aggregate)],\n );\n\n const { subscribe, getSnapShot } = React.useMemo(\n () =>\n makeExternalStore<ObserveAggregationArgs<Q, A>>(\n (observer) =>\n observableClient.observeAggregation(\n {\n type: type,\n where: canonWhere,\n withProperties: stableWithProperties,\n aggregate: stableAggregate,\n dedupeInterval: dedupeIntervalMs ?? 2_000,\n },\n observer,\n ),\n process.env.NODE_ENV !== \"production\"\n ? `aggregation ${type.apiName} ${JSON.stringify(canonWhere)}`\n : void 0,\n ),\n [\n observableClient,\n type.apiName,\n type.type,\n canonWhere,\n stableWithProperties,\n stableAggregate,\n dedupeIntervalMs,\n ],\n );\n\n const payload = React.useSyncExternalStore(subscribe, getSnapShot);\n\n let error: Error | undefined;\n if (payload && \"error\" in payload && payload.error) {\n error = payload.error;\n } else if (payload?.status === \"error\") {\n error = new Error(\"Failed to execute aggregation\");\n }\n\n const refetch = React.useCallback(async () => {\n await observableClient.invalidateObjectType(type.apiName);\n }, [observableClient, type.apiName]);\n\n return {\n data: payload?.result as AggregationsResults<Q, A> | undefined,\n isLoading: payload?.status === \"loading\" || payload?.status === \"init\"\n || !payload,\n error,\n refetch,\n };\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA,OAAOA,KAAK,MAAM,OAAO;AACzB,SAASC,iBAAiB,QAAQ,wBAAwB;AAC1D,SAASC,YAAY,QAAQ,mBAAmB;AAiDhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAKhCC,IAAO,EACP;EACEC,KAAK,GAAG,CAAC,CAAC;EACVC,cAAc;EACdC,SAAS;EACTC;AACmC,CAAC,EACN;EAChC,MAAM;IAAEC;EAAiB,CAAC,GAAGT,KAAK,CAACU,UAAU,CAACR,YAAY,CAAC;EAE3D,MAAMS,UAAU,GAAGF,gBAAgB,CAACG,uBAAuB,CAAIP,KAAK,IAAI,CAAC,CAAC,CAAC;EAE3E,MAAMQ,oBAAoB,GAAGb,KAAK,CAACc,OAAO,CACxC,MAAMR,cAAc,EACpB,CAACS,IAAI,CAACC,SAAS,CAACV,cAAc,CAAC,CACjC,CAAC;EAED,MAAMW,eAAe,GAAGjB,KAAK,CAACc,OAAO,CACnC,MAAMP,SAAS,EACf,CAACQ,IAAI,CAACC,SAAS,CAACT,SAAS,CAAC,CAC5B,CAAC;EAED,MAAM;IAAEW,SAAS;IAAEC;EAAY,CAAC,GAAGnB,KAAK,CAACc,OAAO,CAC9C,MACEb,iBAAiB,CACdmB,QAAQ,IACPX,gBAAgB,CAACY,kBAAkB,CACjC;IACEjB,IAAI,EAAEA,IAAI;IACVC,KAAK,EAAEM,UAAU;IACjBL,cAAc,EAAEO,oBAAoB;IACpCN,SAAS,EAAEU,eAAe;IAC1BK,cAAc,EAAEd,gBAAgB,IAAI;EACtC,CAAC,EACDY,QACF,CAAC,EACHG,OAAO,CAACC,GAAG,CAACC,QAAQ,KAAK,YAAY,GACjC,eAAerB,IAAI,CAACsB,OAAO,IAAIX,IAAI,CAACC,SAAS,CAACL,UAAU,CAAC,EAAE,GAC3D,KAAK,CACX,CAAC,EACH,CACEF,gBAAgB,EAChBL,IAAI,CAACsB,OAAO,EACZtB,IAAI,CAACA,IAAI,EACTO,UAAU,EACVE,oBAAoB,EACpBI,eAAe,EACfT,gBAAgB,CAEpB,CAAC;EAED,MAAMmB,OAAO,GAAG3B,KAAK,CAAC4B,oBAAoB,CAACV,SAAS,EAAEC,WAAW,CAAC;EAElE,IAAIU,KAAwB;EAC5B,IAAIF,OAAO,IAAI,OAAO,IAAIA,OAAO,IAAIA,OAAO,CAACE,KAAK,EAAE;IAClDA,KAAK,GAAGF,OAAO,CAACE,KAAK;EACvB,CAAC,MAAM,IAAIF,OAAO,EAAEG,MAAM,KAAK,OAAO,EAAE;IACtCD,KAAK,GAAG,IAAIE,KAAK,CAAC,+BAA+B,CAAC;EACpD;EAEA,MAAMC,OAAO,GAAGhC,KAAK,CAACiC,WAAW,CAAC,YAAY;IAC5C,MAAMxB,gBAAgB,CAACyB,oBAAoB,CAAC9B,IAAI,CAACsB,OAAO,CAAC;EAC3D,CAAC,EAAE,CAACjB,gBAAgB,EAAEL,IAAI,CAACsB,OAAO,CAAC,CAAC;EAEpC,OAAO;IACLS,IAAI,EAAER,OAAO,EAAES,MAA+C;IAC9DC,SAAS,EAAEV,OAAO,EAAEG,MAAM,KAAK,SAAS,IAAIH,OAAO,EAAEG,MAAM,KAAK,MAAM,IACjE,CAACH,OAAO;IACbE,KAAK;IACLG;EACF,CAAC;AACH","ignoreList":[]}
package/build/types/new/useOsdkAggregation.d.ts CHANGED
@@ -61,6 +61,6 @@ export interface UseOsdkAggregationResult<
61
61
  */
62
62
  export declare function useOsdkAggregation<
63
63
  Q extends ObjectOrInterfaceDefinition,
64
- A extends AggregateOpts<Q>,
64
+ const A extends AggregateOpts<Q>,
65
65
  WP extends DerivedProperty.Clause<Q> | undefined = undefined
66
66
  >(type: Q, { where, withProperties, aggregate, dedupeIntervalMs }: UseOsdkAggregationOptions<Q, A, WP>): UseOsdkAggregationResult<Q, A>;
package/build/types/new/useOsdkAggregation.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"mappings":"AAgBA,cACE,eACA,qBACA,iBACA,6BACA,mBACK,WAAY;AAKnB,cAAc,qBAAqB,YAAa;AAEhD,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;CACxB,kBAAkB,gBAAgB,OAAO;EACzC;;;;CAIA,QAAQ,YAAY,GAAG,cAAc,GAAG;;;;;CAMxC,iBAAiB;;;;CAKjB,WAAW;;;;;;;CAQX;AACD;AAED,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;EACxB;CACA,MAAM,oBAAoB,GAAG;CAC7B;CACA,OAAO;CACP;AACD;;;;;;;;;;;;;;;;;;;;;;;;;AAgCD,OAAO,iBAAS;CACd,UAAU;CACV,UAAU,cAAc;CACxB,WAAW,gBAAgB,OAAO;EAElCA,MAAM,GACN,EACE,OACA,gBACA,WACA,kBACoC,EAAnC,0BAA0B,GAAG,GAAG,MAClC,yBAAyB,GAAG","names":["type: Q"],"sources":["../../../src/new/useOsdkAggregation.ts"],"version":3,"file":"useOsdkAggregation.d.ts"}
1
+ {"mappings":"AAgBA,cACE,eACA,qBACA,iBACA,6BACA,mBACK,WAAY;AAKnB,cAAc,qBAAqB,YAAa;AAEhD,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;CACxB,kBAAkB,gBAAgB,OAAO;EACzC;;;;CAIA,QAAQ,YAAY,GAAG,cAAc,GAAG;;;;;CAMxC,iBAAiB;;;;CAKjB,WAAW;;;;;;;CAQX;AACD;AAED,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;EACxB;CACA,MAAM,oBAAoB,GAAG;CAC7B;CACA,OAAO;CACP;AACD;;;;;;;;;;;;;;;;;;;;;;;;;AAgCD,OAAO,iBAAS;CACd,UAAU;OACJ,UAAU,cAAc;CAC9B,WAAW,gBAAgB,OAAO;EAElCA,MAAM,GACN,EACE,OACA,gBACA,WACA,kBACoC,EAAnC,0BAA0B,GAAG,GAAG,MAClC,yBAAyB,GAAG","names":["type: Q"],"sources":["../../../src/new/useOsdkAggregation.ts"],"version":3,"file":"useOsdkAggregation.d.ts"}
package/docs/advanced-queries.md CHANGED
@@ -474,9 +474,9 @@ function TodoStats() {
474
474
  const { data, isLoading, error } = useOsdkAggregation(Todo, {
475
475
  aggregate: {
476
476
  $select: {
477
- totalCount: { $count: {} },
478
- avgPriority: { $avg: "priority" },
479
- maxDueDate: { $max: "dueDate" },
477
+ $count: "unordered",
478
+ "priority:avg": "unordered",
479
+ "dueDate:max": "unordered",
480
480
  },
481
481
  },
482
482
  });
@@ -489,11 +489,12 @@ function TodoStats() {
489
489
  return <div>Error: {JSON.stringify(error)}</div>;
490
490
  }
491
491
 
492
+ // Results: "propertyName:metric" in $select becomes data.propertyName.metric
492
493
  return (
493
494
  <div>
494
- <p>Total Todos: {data?.totalCount}</p>
495
- <p>Average Priority: {data?.avgPriority}</p>
496
- <p>Latest Due Date: {data?.maxDueDate}</p>
495
+ <p>Total Todos: {data?.$count}</p>
496
+ <p>Average Priority: {data?.priority.avg}</p>
497
+ <p>Latest Due Date: {data?.dueDate.max}</p>
497
498
  </div>
498
499
  );
499
500
  }
@@ -510,8 +511,8 @@ function TodosByStatus() {
510
511
  aggregate: {
511
512
  $groupBy: { status: "exact" },
512
513
  $select: {
513
- count: { $count: {} },
514
- avgPriority: { $avg: "priority" },
514
+ $count: "unordered",
515
+ "priority:avg": "unordered",
515
516
  },
516
517
  },
517
518
  });
@@ -525,8 +526,8 @@ function TodosByStatus() {
525
526
  {data?.map((group, idx) => (
526
527
  <div key={idx}>
527
528
  <h3>Status: {group.$group.status}</h3>
528
- <p>Count: {group.count}</p>
529
- <p>Avg Priority: {group.avgPriority}</p>
529
+ <p>Count: {group.$count}</p>
530
+ <p>Avg Priority: {group.priority.avg}</p>
530
531
  </div>
531
532
  ))}
532
533
  </div>
@@ -545,8 +546,8 @@ function HighPriorityStats() {
545
546
  where: { priority: "high", isComplete: false },
546
547
  aggregate: {
547
548
  $select: {
548
- count: { $count: {} },
549
- earliestDue: { $min: "dueDate" },
549
+ $count: "unordered",
550
+ "dueDate:min": "unordered",
550
551
  },
551
552
  },
552
553
  });
@@ -555,33 +556,38 @@ function HighPriorityStats() {
555
556
 
556
557
  return (
557
558
  <div>
558
- <p>High Priority Incomplete: {data.count}</p>
559
- <p>Earliest Due: {data.earliestDue}</p>
559
+ <p>High Priority Incomplete: {data.$count}</p>
560
+ <p>Earliest Due: {data.dueDate.min}</p>
560
561
  </div>
561
562
  );
562
563
  }
563
564
  ```
564
565
 
565
- ### Aggregation Operators
566
+ ### Aggregation Syntax
566
567
 
567
- - `$count` - Count of objects: `{ $count: {} }`
568
- - `$sum` - Sum of a property: `{ $sum: "propertyName" }`
569
- - `$avg` - Average of a property: `{ $avg: "propertyName" }`
570
- - `$min` - Minimum value: `{ $min: "propertyName" }`
571
- - `$max` - Maximum value: `{ $max: "propertyName" }`
568
+ The `$select` object uses a special key format where each key is a metric and each value is an ordering directive (`"unordered"`, `"asc"`, or `"desc"`). When using `$groupBy`, the ordering determines the order results are returned.
569
+
570
+ **Key formats:**
571
+ - `$count` - Count of objects
572
+ - `"propertyName:sum"` - Sum of a numeric property
573
+ - `"propertyName:avg"` - Average of a numeric property
574
+ - `"propertyName:min"` - Minimum value of a property
575
+ - `"propertyName:max"` - Maximum value of a property
576
+ - `"propertyName:exactDistinct"` - Exact distinct count
577
+ - `"propertyName:approximateDistinct"` - Approximate distinct count (more performant for large datasets)
572
578
 
573
579
  ### Options
574
580
 
575
581
  - `where` - Filter objects before aggregation
576
582
  - `withProperties` - Add derived properties for computed values
577
583
  - `aggregate` - Aggregation configuration:
578
- - `$select` (required) - Object mapping metric names to aggregation operators
584
+ - `$select` (required) - Object mapping metric keys (e.g., `$count`, `"salary:avg"`) to ordering (`"unordered"`, `"asc"`, or `"desc"`)
579
585
  - `$groupBy` (optional) - Object mapping property names to grouping strategy (e.g., `"exact"`, `{ $fixedWidth: 10 }`)
580
586
  - `dedupeIntervalMs` - Minimum time between re-fetches (default: 2000ms)
581
587
 
582
588
  ### Return Values
583
589
 
584
- - `data` - Aggregation result (single object for non-grouped, array for grouped)
590
+ - `data` - Aggregation result (single object for non-grouped, array for grouped). For `$count`, access via `data.$count`. For property metrics like `"salary:avg"`, access via `data.salary.avg`
585
591
  - `isLoading` - True while fetching
586
592
  - `error` - Error object if fetch failed
587
593
  - `refetch` - Manual refetch function
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@osdk/react",
3
- "version": "0.9.0-beta.7",
3
+ "version": "0.9.0-beta.8",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -57,11 +57,11 @@
57
57
  "react": "^18.3.1",
58
58
  "tiny-invariant": "^1.3.3",
59
59
  "typescript": "~5.5.4",
60
- "@osdk/api": "2.7.0-beta.11",
61
- "@osdk/client.test.ontology": "2.7.0-beta.11",
60
+ "@osdk/api": "2.7.0-beta.12",
61
+ "@osdk/client": "2.7.0-beta.12",
62
+ "@osdk/client.test.ontology": "2.7.0-beta.12",
62
63
  "@osdk/monorepo.api-extractor": "~0.6.0-beta.1",
63
- "@osdk/monorepo.tsconfig": "~0.6.0-beta.1",
64
- "@osdk/client": "2.7.0-beta.11"
64
+ "@osdk/monorepo.tsconfig": "~0.6.0-beta.1"
65
65
  },
66
66
  "publishConfig": {
67
67
  "access": "public"