Update README for feedback and throw a TypeError if start_ts and curs…

…or are both provided

README.md

@@ -637,8 +637,7 @@ const changeFeed = client.changeFeed(query);
 
 ### Iterate on a Change Feed
 
-`changeFeed()` returns a `ChangeFeedClient` instance that can act as an `AsyncIterator`. You can
-use a `for await...of` to iterate through all the pages:
+`changeFeed()` returns a `ChangeFeedClient` instance that can act as an `AsyncIterator`. You can use `for await...of` to iterate through all the pages:
 
 ```ts
 const query = fql`Product.all().changesOn(.price, .stock)`;
@@ -706,14 +705,14 @@ try {
 
 ### Change Feed options
 
-The client configuration sets the default options for `changeFeed()`. You can pass a ``ChangeFeedClientConfiguration` object to override these defaults:
+The client configuration sets the default options for `changeFeed()`. You can pass a `ChangeFeedClientConfiguration` object to override these defaults:
 
 ```ts
 const options: ChangeFeedClientConfiguration = {
   long_type: "number",
   max_attempts: 5,
   max_backoff: 1000,
-  secret: "YOUR_FAUNA_SECRET",
+  secret: "FAUNA_SECRET",
   cursor: undefined,
   start_ts: undefined,
 };

__tests__/functional/change-feed-client-configuration.test.ts

@@ -77,4 +77,11 @@ describe("ChangeFeedClientConfiguration", () => {
       expect(e).toBeInstanceOf(RangeError);
     }
   });
+
+  it("throws a TypeError is start_ts and cursor are both provided", async () => {
+    const config = { ...defaultConfig, start_ts: 1, cursor: "cursor" };
+    expect(() => {
+      new ChangeFeedClient(dummyStreamToken, config);
+    }).toThrow(TypeError);
+  });
 });

__tests__/functional/change-feed-client.test.ts

@@ -50,17 +50,6 @@ describe("ChangeFeedClient", () => {
     jest.clearAllMocks();
   });
 
-  it("can be instantiated directly with a token", () => {
-    new ChangeFeedClient(dummyStreamToken, defaultConfig);
-  });
-
-  it("can be instantiated directly with a lambda", async () => {
-    new ChangeFeedClient(
-      () => Promise.resolve(dummyStreamToken),
-      defaultConfig,
-    );
-  });
-
   it("returns a valid page of events", async () => {
     mockHttpClient.request.mockImplementationOnce(() =>
       Promise.resolve({
@@ -184,25 +173,6 @@ describe("ChangeFeedClient", () => {
     );
   });
 
-  it("does not use start_ts if cursor is set", async () => {
-    const startTs = Date.now();
-    const changeFeed = new ChangeFeedClient(dummyStreamToken, {
-      ...defaultConfig,
-      cursor: "cursor=",
-      start_ts: startTs,
-    });
-    await fromAsync(changeFeed.flatten());
-
-    expect(mockHttpClient.request).toHaveBeenCalledWith(
-      expect.objectContaining({
-        data: {
-          token: "dummy",
-          cursor: "cursor=",
-        },
-      }),
-    );
-  });
-
   it("retries throttling errors", async () => {
     mockHttpClient.request.mockImplementationOnce(() =>
       Promise.reject(

src/client.ts

@@ -36,7 +36,6 @@ import {
   StreamToken,
 } from "./values";
 import {
-  QueryFailure,
   ChangeFeedRequest,
   ChangeFeedSuccess,
   EncodedObject,
@@ -49,6 +48,7 @@ import {
   StreamEventStatus,
   type QuerySuccess,
   type QueryValue,
+  ChangeFeedError,
 } from "./wire-protocol";
 
 type RequiredClientConfig = ClientConfiguration &
@@ -1013,6 +1013,7 @@ export class ChangeFeedClient<T extends QueryValue = any> {
     }
 
     // If we have a cursor, use that. Otherwise, use the start_ts if available.
+    // When the config is validated, if both are set, an error is thrown.
     if (this.#lastCursor) {
       req.data.cursor = this.#lastCursor;
     } else if (this.#clientConfiguration.start_ts) {
@@ -1046,7 +1047,7 @@ export class ChangeFeedClient<T extends QueryValue = any> {
       shouldRetry: (error) => error instanceof ThrottlingError,
     });
 
-    let body: ChangeFeedSuccess<T> | QueryFailure;
+    let body: ChangeFeedSuccess<T> | ChangeFeedError;
 
     try {
       body = TaggedTypeFormat.decode(response.body, {
@@ -1131,6 +1132,12 @@ export class ChangeFeedClient<T extends QueryValue = any> {
     if (config.max_attempts <= 0) {
       throw new RangeError(`'max_attempts' must be greater than zero.`);
     }
+
+    if (config.start_ts !== undefined && config.cursor !== undefined) {
+      throw new TypeError(
+        "Only one of 'start_ts' or 'cursor' can be defined in the client configuration.",
+      );
+    }
   }
 }