feat: Add DQL support #65

pvditto · 2024-09-20T13:55:19Z

Adds support for DQL by adding two new hooks: useQuery() and useExecuteQuery(). See original API design (internal).

Replaces the Vite example app with a DQL version and moves the query builder-based one to examples/vite-typescript-example-legacy.
Updates CI to build both example apps.
Update the quick start section in the readme
Includes comprehensive tests and API references

The minimum supported version of @dittolive/ditto changes to 4.8.1 (4.10.0 in the example to support customAuthURL).

Usage

A quick overview, refer to the API reference for more details.

The useQuery() hook immediately sets up a store observer and sync subscription for a given query. This hook only supports non-mutating DQL syntax.

 const { items } = useQuery(
   'select * from tasks where _id = :id limit 10', {
     queryArguments: { id: '123' },
   }
 )

The useExecuteQuery() hook returns a function that can be called to execute a query on demand, e.g. for mutating data or reacting to user actions.

```tsx
const [executeQuery] = useExecuteQuery(
  'insert into tasks documents (:task)',
  {
    queryArguments: { task: { author: 'Alice' } },
  },
)

// Clicking the button will execute the query with query arguments
// `{ task: { author: 'Alice', description: 'Buy milk' } }`.
return <button
 onClick={() => executeQuery({ task: { description: 'Buy milk' } })}
>Add Task</button>

Out of scope

This lib does not yet support the new Ditto 4.12+ configuration syntax
The example still only supports offline playground and online with authentication, no online playground
This example should probably be aligned more closely with https://github.com/getditto/quickstart

- Add useQuery hook for reactive queries with sync subscriptions - Add useExecuteQuery hook for one-time query execution - Update example app to use DQL instead of collection-based API - Rename old example to vite-typescript-example-legacy - Update CI to test both DQL and legacy examples

- disable sync with v3 - install websocket url - disable Ditto cloud sync - actually start sync

…nstructions

… of cursor-based hooks

src/queries/useExecuteQuery.ts

src/queries/useQuery.ts

tdwells90 · 2025-08-12T14:49:21Z

src/queries/useQuery.ts

+export function useQuery<
+  // We default to any here and let the user specify the type if they want.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T = any,


I'd prefer unknown here, but I see it's technically optional so I guess it's ok. I don't think there's any harm in forcing the user to specify types, personally!

I am also a fan of stricter type safety from defaulting to unknown

tdwells90 · 2025-08-12T14:53:34Z

src/queries/useExecuteQuery.ts

+        nextDitto = dittoHash[persistenceDirectory ?? Object.keys(dittoHash)[0]]
+      }
+
+      if (nextDitto == null) {


I would prefer strict equality here === but I think !nextDitto would also work. Not a big issue, though.

tdwells90 · 2025-08-12T14:56:47Z

src/queries/useExecuteQuery.ts

+      let finalQueryArguments: U = {} as U
+      if (queryArguments) {
+        finalQueryArguments = Object.assign(finalQueryArguments, queryArguments)
+      }
+
+      if (localQueryArguments) {
+        finalQueryArguments = Object.assign(
+          finalQueryArguments,
+          localQueryArguments,
+        )
+      }


I think this could be simplified like this:

const finalQueryArguments = { ...queryArguments, ...localQueryArguments, } as U

Or if you need to handle null/undefined values explicitly:

const finalQueryArguments = { ...(queryArguments || {}), ...(localQueryArguments || {}), } as U

aaronleopold

I had a couple very low priority questions/comments, but I think this looks good!

aaronleopold · 2025-08-12T14:52:58Z

README.md

-    collection: 'tasks',
-  })
+  // Query documents using DQL
+  const { documents } = useQuery<Task>('SELECT * FROM tasks WHERE isCompleted = false')


Would it be worth having a note about type coercion here? I know it is called out in the doc comments for the hook, so perhaps that is good enough

aaronleopold · 2025-08-12T15:17:34Z

src/queries/useQuery.spec.tsx

+  persistenceDirectory: uuidv4(),
+})
+
+export const DocumentUpserter: React.FC<{ persistenceDirectory: string }> = ({


Nit: React.FC is generally discouraged, as I understand it. Since it is used for tests here, I don't think it matters much, though.

aaronleopold · 2025-08-12T15:20:24Z

src/queries/useQuery.ts

+export function useQuery<
+  // We default to any here and let the user specify the type if they want.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T = any,


I am also a fan of stricter type safety from defaulting to unknown

teodorciuraru · 2025-08-14T16:05:59Z

Can we get Copilot on this one?

Copilot

Pull Request Overview

Adds support for DQL (Ditto Query Language) by introducing two new React hooks: useQuery() for continuous query observation and useExecuteQuery() for on-demand query execution. The PR replaces the existing Vite example with a DQL-based implementation and moves the query builder example to a legacy folder.

Adds useQuery() hook for real-time document subscriptions with DQL syntax
Adds useExecuteQuery() hook for executing queries on demand (mutations and ad-hoc queries)
Updates minimum Ditto version requirement to 4.8.1+ and example to use 4.10.0+

Reviewed Changes

Copilot reviewed 32 out of 42 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`src/queries/useQuery.ts`	Implements the main `useQuery` hook with store observer and sync subscription setup
`src/queries/useExecuteQuery.ts`	Implements the `useExecuteQuery` hook for on-demand query execution
`src/queries/useQuery.spec.tsx`	Comprehensive test suite for the `useQuery` hook functionality
`src/queries/useExecuteQuery.spec.tsx`	Comprehensive test suite for the `useExecuteQuery` hook functionality
`examples/vite-typescript-example/src/App.tsx`	Updates example app to use DQL hooks instead of query builder API
`examples/vite-typescript-example/src/AppContainer.tsx`	Updates Ditto configuration for newer API and cloud setup
`examples/vite-typescript-example/src/AuthenticationPanel.tsx`	Updates authentication method call from `loginWithToken` to `login`
`package.json`	Updates peer dependency version requirements for Ditto

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-15T09:56:29Z

src/queries/useQuery.ts

+      }
+    }
+
+    setQueryResult(null)


Setting queryResult to null conflicts with the TypeScript type QueryResult<T> | undefined declared on line 134. The setQueryResult function expects QueryResult<T> | undefined but null is being passed.

Suggested change

setQueryResult(null)

setQueryResult(undefined)

Copilot · 2025-08-15T09:56:30Z

src/queries/useExecuteQuery.ts

+ * >Add Task</button>
+ * ```
+ *
+ * @param query - The query to run. Must be a non-mutating query.


The documentation states the query must be non-mutating, but useExecuteQuery is specifically designed for mutating queries as shown in the examples and description. This comment appears to be copied from useQuery and should be corrected.

Suggested change

* @param query - The query to run. Must be a non-mutating query.

* @param query - The query to run. May be a mutating query.

Copilot · 2025-08-15T09:56:30Z

src/queries/useExecuteQuery.ts

+      localQueryArguments?: Partial<U>,
+      localOnError?: (error: unknown) => void,
+    ) => {
+      setItems(null)


Setting items to null conflicts with the TypeScript type QueryResultItem[] | undefined declared on line 200. The setItems function expects QueryResultItem[] | undefined but null is being passed.

Suggested change

setItems(null)

setItems(undefined)

Copilot · 2025-08-15T09:56:30Z

src/queries/useExecuteQuery.ts

+      localOnError?: (error: unknown) => void,
+    ) => {
+      setItems(null)
+      setMutatedDocumentIDs(null)


Setting mutatedDocumentIDs to null conflicts with the TypeScript type DocumentID[] | undefined declared on line 202. The setMutatedDocumentIDs function expects DocumentID[] | undefined but null is being passed.

Suggested change

setMutatedDocumentIDs(null)

setMutatedDocumentIDs(undefined)

Copilot · 2025-08-15T09:56:30Z

src/queries/useExecuteQuery.ts

+  const reset = useCallback(() => {
+    setError(null)
+    setItems(undefined)
+    setMutatedDocumentIDs(null)


Setting mutatedDocumentIDs to null conflicts with the TypeScript type DocumentID[] | undefined declared on line 202. The setMutatedDocumentIDs function expects DocumentID[] | undefined but null is being passed.

Suggested change

setMutatedDocumentIDs(null)

setMutatedDocumentIDs(undefined)

Copilot · 2025-08-15T09:56:31Z

examples/vite-typescript-example/src/AppContainer.tsx

            return <h1>Loading</h1>
          }
          if (error) {
+            if (error) console.error('Error creating Ditto instances:', error)


The condition if (error) is redundant since it's already inside an if (error) block on line 98. This creates a duplicated check that serves no purpose.

Suggested change

if (error) console.error('Error creating Ditto instances:', error)

console.error('Error creating Ditto instances:', error)

pvditto · 2025-08-15T16:23:51Z

Looks like there are some good suggestions from Copilot, I will continue here after my PTO, didn't get this done today.

pvditto added 13 commits September 16, 2024 16:25

Add useQuery hook

8c0091f

Add DQL create-react-app example

9ab59c9

Add tests

f8eeae8

Add useExecuteQuery hook

dc6d1a8

Update useQuery to use generics

ecedec8

Update useQuery error type

2074928

Add test:watch command

d4d2ee2

Cleanup

7b63f57

Update required Ditto version

9fd3db8

Reenable lazy provider test

83365d8

Fix query arguments merging

46cd116

Fix deep comparison on query arguments

62c6d85

WIP update example app

d987ae4

pvditto added the enhancement New feature or request label Sep 20, 2024

pvditto self-assigned this Sep 20, 2024

Base automatically changed from pv/esm-export to master September 25, 2024 08:48

pvditto added 12 commits August 11, 2025 18:53

Merge master and resolve yarn.lock conflict

e44c0b2

Rename existing example

c70b70a

fix: update authentication method to use login instead of loginWithToken

4f8ab98

Update Ditto API usage

8f96228

- disable sync with v3 - install websocket url - disable Ditto cloud sync - actually start sync

docs: update README to include Ditto authentication setup and usage i…

f1daedb

…nstructions

Update logo

2e46db6

Add comment

b61f241

Clean up

ea17e85

Fix CI workflow: build main package before examples

13749e7

Update quick start instructions for DQL

ec46d04

Update README to use DQL hooks (useQuery and useExecuteQuery) instead…

522cf15

… of cursor-based hooks

pvditto requested review from teodorciuraru and tdwells90 August 12, 2025 11:12

pvditto requested review from jreyes33 and aaronleopold August 12, 2025 11:13

pvditto marked this pull request as ready for review August 12, 2025 11:14

tdwells90 reviewed Aug 12, 2025

View reviewed changes

src/queries/useExecuteQuery.ts Show resolved Hide resolved

tdwells90 reviewed Aug 12, 2025

View reviewed changes

src/queries/useQuery.ts Show resolved Hide resolved

tdwells90 reviewed Aug 12, 2025

View reviewed changes

aaronleopold reviewed Aug 12, 2025

View reviewed changes

pvditto requested a review from Copilot August 15, 2025 09:55

Copilot AI reviewed Aug 15, 2025

View reviewed changes

	* @param query - The query to run. Must be a non-mutating query.
	* @param query - The query to run. May be a mutating query.

	if (error) console.error('Error creating Ditto instances:', error)
	console.error('Error creating Ditto instances:', error)

feat: Add DQL support #65

Are you sure you want to change the base?

feat: Add DQL support #65

Uh oh!

Conversation

pvditto commented Sep 20, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

Out of scope

Uh oh!

Uh oh!

Uh oh!

tdwells90 Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

aaronleopold Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdwells90 Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdwells90 Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

aaronleopold left a comment

Choose a reason for hiding this comment

Uh oh!

aaronleopold Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

aaronleopold Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

aaronleopold Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

teodorciuraru commented Aug 14, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

pvditto commented Aug 15, 2025

Uh oh!

Uh oh!

pvditto commented Sep 20, 2024 •

edited

Loading

aaronleopold Aug 12, 2025 •

edited

Loading

tdwells90 Aug 12, 2025 •

edited

Loading

aaronleopold Aug 12, 2025 •

edited

Loading