@pulseindex/sdk 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,84 +1,56 @@
 # Changelog
 
-## 2.0.0
-
-### Breaking: three methods removed
-
-`createSnapshot()`, `getRecoveryState()` and `setCdcOffset()` are gone, along
-with the `RecoveryState`, `CreateSnapshotResponse` and `SetCdcOffsetResponse`
-types and the RPCs behind them in the bundled proto.
-
-No key issued from the dashboard could call them — every attempt returned a
-permission error — so nothing that worked before stops working. If you were
-calling them and getting errors, that is the code to delete.
-
-**Checking readiness:** use `health()`, or `servingStatus()` when you need to
-tell "not answering" apart from "not reachable". Both work with any key.
-
-### The bundled proto now describes only the client's contract
+## 3.0.0
 
-Four RPCs: `IndexEntity`, `BatchIndexEntities`, `DeleteEntity`, `Search`. The
-drift check that keeps this file honest was changed to match: it verifies every
-declaration here exists identically in the service, and no longer requires the
-two to be identical.
+### Breaking: a query returns a page instead of everything
 
-## 1.1.4
+`QueryBuilder` defaulted to a limit of 0, which the engine read as "no
+ceiling" and answered with every matching id the tenant held. Nobody calling
+`search()` without a limit meant to ask for that, and the cost of it landed on
+the service rather than on the caller who never mentioned one.
 
-Documentation only.
+The default is now `DEFAULT_LIMIT`, a hundred, on the builder and on the plain
+options object alike. If you relied on getting every match back, say so:
 
-The README documented three methods no ordinary API key can call, and explained
-that they need an elevated one. That is operator surface, and it was dead
-reading for anyone the README is written for. It also named the server-side
-environment variable that holds API keys, which is not the client's business.
+```ts
+await client.search(PulseIndex.query().tenant('acme').must('status:active').limit(5000));
+```
 
-`health()` is now described by what it tells you rather than by the protocol
-underneath it, and the production example uses a real endpoint.
+A limit above the engine's maximum is refused with the maximum named, rather
+than quietly trimmed — a short page that looks complete is worse than an error.
 
-The methods still exist on the client; they are simply no longer presented as
-part of the product.
+### Zero now means the count
 
-## 1.1.3
+`limit(0)` no longer means "no ceiling". It asks the engine for the number of
+matches and no ids at all, which is the cheap way to count:
 
-No code change. The package now ships only what is needed to use it.
+```ts
+const { totalMatches } = await client.search(
+  PulseIndex.query().tenant('acme').must('status:active').limit(0),
+);
+```
 
-- Source maps are no longer published. They embedded the complete TypeScript
-  source of every bundled file and were 59% of the tarball. The shipped
-  JavaScript is unminified, so stack traces still land somewhere readable.
-- Build, release and proto-sync notes moved out of the README; they described
-  how the SDK is maintained, not how to call it.
-- The RPC table lists the calls a normal API key can make. The three
-  operator-only ones are noted rather than tabulated.
+Requires an engine that speaks this contract. Against an older engine, a limit
+of 0 still returns every id.
 
-318 KB to 130 KB.
-
-## 1.1.2
-
-Documentation only; the code is identical to 1.1.0.
-
-The vendored `engine.proto` still described how the service works rather than
-how to call it. Found by reading the file rather than searching it for known
-words — which is the only method that finds what you did not already know to
-look for.
-
-## 1.1.1
+## 2.0.0
 
-Documentation only; the code is identical to 1.1.0.
+### Breaking: the operator-only methods are gone
 
-1.1.0 shipped internal maintainer comments in its type declarations and source
-maps — `tsup` emits JSDoc into `.d.ts` and embeds the whole TypeScript source
-into `.map`, and both are in the tarball. 1.1.0 has been unpublished.
+Three methods that no API key could ever call have been removed, along with
+their types. Every attempt returned a permission error, so nothing that worked
+before stops working. If you were calling them and handling the failure, that
+is the code to delete.
 
-## 1.1.0
+**Checking readiness:** use `health()`, or `servingStatus()` when you need to
+tell "not answering" apart from "not reachable". Both work with any key.
 
 ### `health()` no longer reports false for every key
 
-`health()` used an operator-only call that customer API keys are not permitted to
-make. The permission error was caught and turned into `false`, so the method
-reported an unusable service no matter how healthy it actually was.
-
-It now uses the standard `grpc.health.v1.Health` protocol, which requires no
-particular scope. The signature is unchanged. If you were working around this by
-ignoring `health()`, you can stop.
+`health()` returned `false` no matter how the service was actually doing. It
+now uses the standard `grpc.health.v1.Health` protocol. The signature is
+unchanged — if you were working around this by ignoring `health()`, you can
+stop.
 
 ### Added
 
@@ -89,7 +61,7 @@ ignoring `health()`, you can stop.
 - `healthProtoPath` on the client config, for the rare case of overriding the
   bundled `health.proto`.
 
-`proto/health.proto` now ships with the package. It is the standard health
+`proto/health.proto` ships with the package. It is the standard health
 protocol, vendored rather than pulled in as a dependency.
 
 ### Compatibility
@@ -97,6 +69,6 @@ protocol, vendored rather than pulled in as a dependency.
 Against a service deployed before this release, the health protocol answers but
 always reports `SERVING`. `health()` is then equivalent to a reachability check.
 
-## 1.0.0
+## Earlier versions
 
-Initial release.
+1.x was withdrawn and is not installable. 2.0.0 is the first supported release.

package/dist/index.d.mts

@@ -138,6 +138,15 @@ interface PulseIndexClientConfig {
 interface QueryExecutor {
     search(query: QueryBuilder): Promise<SearchResponse>;
 }
+/**
+ * A page, for callers who never say otherwise.
+ *
+ * The default used to be 0, which the engine read as "no ceiling" and answered
+ * with every matching id the tenant held. Nobody meant to ask for that, and
+ * the cost of it landed on the service rather than on the caller who forgot
+ * the limit. Zero is still expressible and now means the total alone.
+ */
+declare const DEFAULT_LIMIT = 100;
 declare class QueryBuilder {
     private readonly executor;
     private state;
@@ -152,6 +161,10 @@ declare class QueryBuilder {
     withinRadius(lat: number, lon: number, radiusKm: number, precision?: number): QueryBuilder;
     withinRadius(options: RadiusOptions): QueryBuilder;
     range(field: string, min: number, max: number): QueryBuilder;
+    /**
+     * How many ids to return. Zero asks the engine for the number of matches
+     * and no ids at all, which is the cheap way to count.
+     */
     limit(limit: number): QueryBuilder;
     offset(offset: number): QueryBuilder;
     toRequest(defaultTenantId?: string): SearchQueryRequest;
@@ -321,4 +334,4 @@ declare class PulseIndexQueryError extends PulseIndexError {
     constructor(message: string, options?: ConstructorParameters<typeof PulseIndexError>[1]);
 }
 
-export { type BatchEntityInput, type BatchIndexResponse, ConnectionManager, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };
+export { type BatchEntityInput, type BatchIndexResponse, ConnectionManager, DEFAULT_LIMIT, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };

package/dist/index.d.ts

@@ -138,6 +138,15 @@ interface PulseIndexClientConfig {
 interface QueryExecutor {
     search(query: QueryBuilder): Promise<SearchResponse>;
 }
+/**
+ * A page, for callers who never say otherwise.
+ *
+ * The default used to be 0, which the engine read as "no ceiling" and answered
+ * with every matching id the tenant held. Nobody meant to ask for that, and
+ * the cost of it landed on the service rather than on the caller who forgot
+ * the limit. Zero is still expressible and now means the total alone.
+ */
+declare const DEFAULT_LIMIT = 100;
 declare class QueryBuilder {
     private readonly executor;
     private state;
@@ -152,6 +161,10 @@ declare class QueryBuilder {
     withinRadius(lat: number, lon: number, radiusKm: number, precision?: number): QueryBuilder;
     withinRadius(options: RadiusOptions): QueryBuilder;
     range(field: string, min: number, max: number): QueryBuilder;
+    /**
+     * How many ids to return. Zero asks the engine for the number of matches
+     * and no ids at all, which is the cheap way to count.
+     */
     limit(limit: number): QueryBuilder;
     offset(offset: number): QueryBuilder;
     toRequest(defaultTenantId?: string): SearchQueryRequest;
@@ -321,4 +334,4 @@ declare class PulseIndexQueryError extends PulseIndexError {
     constructor(message: string, options?: ConstructorParameters<typeof PulseIndexError>[1]);
 }
 
-export { type BatchEntityInput, type BatchIndexResponse, ConnectionManager, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };
+export { type BatchEntityInput, type BatchIndexResponse, ConnectionManager, DEFAULT_LIMIT, type DeleteResponse, type EncodedEntity, type EntityAttributes, type EntityId, type EntityInput, FilterOperation, type FilterPredicate, GeoHash, type IndexEntityRequest, type IndexEntityResponse, PulseIndex, PulseIndexAuthError, PulseIndexClient, type PulseIndexClientConfig, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, type RadiusOptions, type RangePredicate, SERVING_STATUS, type SearchQueryRequest, type SearchRequestOptions, type SearchResponse, PulseIndex as default, encodeEntity, sslEnabled, toUint64String };

package/dist/index.js

@@ -384,11 +384,12 @@ var DEFAULT_TIMEOUT_MS = 5e3;
 var DEFAULT_POOL_SIZE = 1;
 
 // src/builder/QueryBuilder.ts
+var DEFAULT_LIMIT = 100;
 function emptyState() {
   return {
     tenantId: "",
     locationPrefix: "0",
-    limit: 0,
+    limit: DEFAULT_LIMIT,
     offset: 0,
     filters: [],
     ranges: []
@@ -488,6 +489,10 @@ var QueryBuilder = class _QueryBuilder {
       });
     });
   }
+  /**
+   * How many ids to return. Zero asks the engine for the number of matches
+   * and no ids at all, which is the cheap way to count.
+   */
   limit(limit) {
     return this.fork((state) => {
       state.limit = Math.max(0, Math.floor(limit));
@@ -1179,6 +1184,7 @@ function toIndexRequest(encoded) {
 var index_default = PulseIndex;
 
 exports.ConnectionManager = ConnectionManager;
+exports.DEFAULT_LIMIT = DEFAULT_LIMIT;
 exports.FilterOperation = FilterOperation;
 exports.GeoHash = GeoHash;
 exports.PulseIndex = PulseIndex;

package/dist/index.mjs

@@ -361,11 +361,12 @@ var DEFAULT_TIMEOUT_MS = 5e3;
 var DEFAULT_POOL_SIZE = 1;
 
 // src/builder/QueryBuilder.ts
+var DEFAULT_LIMIT = 100;
 function emptyState() {
   return {
     tenantId: "",
     locationPrefix: "0",
-    limit: 0,
+    limit: DEFAULT_LIMIT,
     offset: 0,
     filters: [],
     ranges: []
@@ -465,6 +466,10 @@ var QueryBuilder = class _QueryBuilder {
       });
     });
   }
+  /**
+   * How many ids to return. Zero asks the engine for the number of matches
+   * and no ids at all, which is the cheap way to count.
+   */
   limit(limit) {
     return this.fork((state) => {
       state.limit = Math.max(0, Math.floor(limit));
@@ -1155,4 +1160,4 @@ function toIndexRequest(encoded) {
 // src/index.ts
 var index_default = PulseIndex;
 
-export { ConnectionManager, FilterOperation, GeoHash, PulseIndex, PulseIndexAuthError, PulseIndexClient, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, SERVING_STATUS, index_default as default, encodeEntity, sslEnabled, toUint64String };
+export { ConnectionManager, DEFAULT_LIMIT, FilterOperation, GeoHash, PulseIndex, PulseIndexAuthError, PulseIndexClient, PulseIndexConnectionError, PulseIndexError, PulseIndexQueryError, QueryBuilder, SERVING_STATUS, index_default as default, encodeEntity, sslEnabled, toUint64String };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulseindex/sdk",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Official Node.js & TypeScript SDK for PulseIndex — hosted search and filtering for large entity sets",
   "license": "MIT",
   "author": "PulseIndex",