;
38 | /**
39 | * The cancel function, used to cancel the query.
40 | */
41 | cancel?: () => void;
42 | /**
43 | * Whether the query is enabled.
44 | */
45 | enabled?: boolean;
46 | /**
47 | * The unique id for the query.
48 | */
49 | queryId?: string;
50 | };
51 |
52 | /**
53 | * Options passed to AsyncQuery.viewUpdate
54 | * @see {AsyncQuery.viewUpdate}
55 | */
56 | export type AsyncQueryViewUpdateOptions = {
57 | /**
58 | * If true the query will not dispatch a transaction for `canceled` queries
59 | */
60 | ignoreCanceled?: boolean;
61 | /**
62 | * If true the query will not dispatch a transaction for `successful` queries
63 | */
64 | ignoreSuccess?: boolean;
65 | /**
66 | * If true the query will not dispatch a transaction for `error` queries.
67 | *
68 | * Note: all canceled queries are errors, but not all errors are canceled.
69 | * You can determine if a query was canceled by checking that both the `error`
70 | * property and the `canceled` property are true.
71 | */
72 | ignoreError?: boolean;
73 | /**
74 | * If true the query will not dispatch a transaction for `loading` queries
75 | */
76 | ignoreLoading?: boolean;
77 | };
78 |
79 | /**
80 | * AsyncQuery is a helper class for handling asynchronous functions in ProseMirror.
81 | * The basic logic idea is that you pass an async function to the query in apply.
82 | * You then run `viewUpdate` and`viewDestroy` in the state update/destroy functions.
83 | * The query will dispatch transactions when the async update is finished.
84 | * You can handle these transactions in apply using statusChanged()
85 | * and use them to build state to display in update.
86 | */
87 | export class AsyncQuery {
88 | /**
89 | * @see {AsyncQueryOptions.enabled}
90 | */
91 | public enabled: boolean;
92 | /**
93 | * @see {AsyncQueryOptions.parameters}
94 | */
95 | public parameters: P | undefined;
96 | /**
97 | * @see {AsyncQueryOptions.metaKey}
98 | */
99 | public readonly metaKey: MetaKey;
100 | /**
101 | * @see {AsyncQueryOptions.queryId}
102 | */
103 | public readonly queryId: string;
104 |
105 | private _canceled: boolean;
106 | private _data: D | undefined;
107 | private _error: any | undefined;
108 | private _status: QueryStatus;
109 | private cancelFn: (() => void) | undefined;
110 | private queryFn: () => Promise;
111 |
112 | /**
113 | * @see {QueryStatus}
114 | */
115 | public get status() {
116 | return this._status;
117 | }
118 |
119 | /**
120 | * The data returned by the query
121 | */
122 | public get data() {
123 | return this._data;
124 | }
125 |
126 | /**
127 | * The error returned by the query
128 | */
129 | public get error() {
130 | return this._error;
131 | }
132 |
133 | /**
134 | * Whether the query was canceled.
135 | */
136 | public get canceled() {
137 | return this._canceled;
138 | }
139 |
140 | /**
141 | * String representation of the query
142 | */
143 | public toString() {
144 | return `Query(${this.parameters}) { status: ${this.status}, canceled: ${this.canceled}, enabled: ${this.enabled} }`;
145 | }
146 |
147 | /**
148 | * Create a new AsyncQuery
149 | *
150 | * @see {AsyncQueryOptions}
151 | */
152 | constructor({ metaKey, parameters, query, cancel, enabled, queryId }: AsyncQueryOptions) {
153 | this._status = "idle";
154 | this.queryFn = query ?? (() => Promise.resolve() as any);
155 | this.cancelFn = cancel;
156 | this.parameters = parameters;
157 | this._canceled = false;
158 | this.metaKey = metaKey ?? nanoid();
159 | this.queryId = queryId ?? nanoid();
160 | this.enabled = enabled ?? true;
161 | }
162 |
163 | /**
164 | * Run the query, setting the query's data, status, error, and canceled
165 | * appropriately.
166 | *
167 | * @returns Promise that resolves when the query function returns or when the
168 | * query is canceled.
169 | */
170 | public async run() {
171 | if (this.enabled === false) {
172 | return;
173 | }
174 | this._status = "loading";
175 | this._canceled = false;
176 | return this.queryFn()
177 | .then((res) => {
178 | if (this._canceled) {
179 | throw new Error("Canceled");
180 | }
181 | this._data = res;
182 | this._status = "success";
183 | })
184 | .catch((err) => {
185 | this._status = "error";
186 | this._error = err;
187 | });
188 | }
189 |
190 | /**
191 | * Cancel the query
192 | */
193 | public cancel() {
194 | if (this._status === "loading") {
195 | this._status = "error";
196 | this._canceled = true;
197 | this._error = new Error("Canceled");
198 | this.cancelFn?.();
199 | }
200 | }
201 |
202 | /**
203 | * Method meant to be called in a prosemirror plugin's view.update method. If
204 | * the query idle this method runs the query and will dispatch transactions
205 | * indicating changes to the query status such as `loading`, `error`, and
206 | * `success`.
207 | *
208 | * This function only runs the query function if the query is `idle` and is
209 | * `enabled`.
210 | *
211 | * You can pass options to suppress transactions associated with certain updates.
212 | * For example you can ignore `loading` and `canceled` queries by passing
213 | * `{ignoreLoading: true, ignoreCanceled: true}`.
214 | */
215 | public viewUpdate(
216 | editor: EditorView,
217 | {
218 | ignoreCanceled = false,
219 | ignoreError = false,
220 | ignoreLoading = false,
221 | ignoreSuccess = false,
222 | }: AsyncQueryViewUpdateOptions = {},
223 | ) {
224 | if (this.enabled === false) {
225 | return;
226 | }
227 | if (this.status === "idle") {
228 | // run all idle queries
229 | this.run().finally(() => {
230 | if (this._canceled && ignoreCanceled) {
231 | return;
232 | }
233 | if (this.status === "success" && ignoreSuccess) {
234 | return;
235 | }
236 |
237 | if (this.status === "error" && ignoreError) {
238 | return;
239 | }
240 |
241 | const transaction = editor.state.tr;
242 | transaction.setMeta("addToHistory", false);
243 | transaction.setMeta(this.metaKey, {
244 | queryId: this.queryId,
245 | });
246 | editor.dispatch(transaction);
247 | });
248 |
249 | if (ignoreLoading) {
250 | return;
251 | }
252 |
253 | // send loading updates
254 | const transaction = editor.state.tr;
255 | transaction.setMeta("addToHistory", false);
256 | transaction.setMeta(this.metaKey, {
257 | queryId: this.queryId,
258 | });
259 | editor.dispatch(transaction);
260 | }
261 | }
262 |
263 | /**
264 | * Method meant to be called in a prosemirror plugin's view.destory method.
265 | * This method cancels any running queries.
266 | */
267 | public viewDestroy() {
268 | this.cancel();
269 | }
270 |
271 | /**
272 | * Method meant to be called in a prosemirror plugin's state.apply method.
273 | *
274 | * This method checks the transaction to see if it is a transaction dispatched
275 | * from the viewUpdate method.
276 | *
277 | * You can filter transactions by passing a status string or array.
278 | * If status equals `success` the method will only return true for transactions
279 | * where the query successfully returned.
280 | *
281 | * If status equals [`success`, `error`] the method will only return true for
282 | * transactions where the query returned successfully or threw an error.
283 | *
284 | */
285 | public statusChanged(tr: Transaction, status?: QueryStatus | QueryStatus[]): boolean {
286 | let reportChange = tr.getMeta(this.metaKey)?.queryId === this.queryId;
287 | if (typeof status === "string") {
288 | reportChange = this.status === status && reportChange;
289 | } else if (Array.isArray(status)) {
290 | reportChange = status.indexOf(this.status) !== -1 && reportChange;
291 | }
292 | return reportChange;
293 | }
294 |
295 | /**
296 | * Create an empty query that is disabled. This query will not do anything
297 | * but can be useful for setting initial prosemirror plugin state in state.init.
298 | */
299 | public static empty() {
300 | return new AsyncQuery({
301 | enabled: false,
302 | });
303 | }
304 | }
305 |
--------------------------------------------------------------------------------
/lib/main.ts:
--------------------------------------------------------------------------------
1 | export { AsyncQuery } from "./AsyncQuery";
2 | export type { AsyncQueryOptions, AsyncQueryViewUpdateOptions, MetaKey, QueryStatus } from "./AsyncQuery";
3 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "prosemirror-async-query",
3 | "files": [
4 | "dist"
5 | ],
6 | "types": "./dist/main.d.ts",
7 | "main": "./dist/prosemirror-async-query.umd.js",
8 | "module": "./dist/prosemirror-async-query.es.js",
9 | "exports": {
10 | ".": {
11 | "import": "./dist/prosemirror-async-query.es.js",
12 | "require": "./dist/prosemirror-async-query.umd.js"
13 | }
14 | },
15 | "license": "MIT",
16 | "repository": {
17 | "type": "git",
18 | "url": "https://github.com/lukesmurray/prosemirror-async-query.git"
19 | },
20 | "bugs": {
21 | "url": "https://github.com/lukesmurray/prosemirror-async-query/issues"
22 | },
23 | "scripts": {
24 | "dev": "vite --config vite.example.config.ts",
25 | "build:example": "vite build --config vite.example.config.ts",
26 | "build:lib": "vite build --config vite.lib.config.ts",
27 | "build": "tsc && yarn build:lib && yarn build:example",
28 | "prepublishOnly": "yarn build",
29 | "serve": "vite preview --config vite.example.config.ts"
30 | },
31 | "peerDependencies": {
32 | "prosemirror-state": "^1.3.4",
33 | "prosemirror-view": "^1.23.3"
34 | },
35 | "dependencies": {
36 | "nanoid": "^3.1.30"
37 | },
38 | "devDependencies": {
39 | "@rollup/plugin-typescript": "^8.3.0",
40 | "@tiptap/core": "^2.0.0-beta.158",
41 | "@tiptap/extension-document": "^2.0.0-beta.15",
42 | "@tiptap/extension-history": "^2.0.0-beta.21",
43 | "@tiptap/extension-paragraph": "^2.0.0-beta.23",
44 | "@tiptap/extension-text": "^2.0.0-beta.15",
45 | "@tiptap/react": "^2.0.0-beta.101",
46 | "@types/react": "^17.0.33",
47 | "@types/react-dom": "^17.0.10",
48 | "@typescript-eslint/eslint-plugin": "^5.8.0",
49 | "@typescript-eslint/parser": "^5.8.0",
50 | "@vitejs/plugin-react": "^1.0.7",
51 | "console-feed": "^3.2.2",
52 | "eslint": "^7.31.0",
53 | "eslint-config-prettier": "^8.3.0",
54 | "eslint-plugin-prettier": "^3.4.0",
55 | "eslint-plugin-react": "^7.24.0",
56 | "eslint-plugin-react-hooks": "^4.2.0",
57 | "memoize-one": "^6.0.0",
58 | "open-color": "^1.9.1",
59 | "prettier": "^2.3.2",
60 | "react": "^17.0.2",
61 | "react-dom": "^17.0.2",
62 | "sass": "^1.45.0",
63 | "tiny-invariant": "^1.2.0",
64 | "typescript": "^4.4.4",
65 | "vite": "^2.7.2"
66 | },
67 | "sideEffects": false,
68 | "version": "0.0.4"
69 | }
70 |
--------------------------------------------------------------------------------
/src/AsyncFlowExtension.tsx:
--------------------------------------------------------------------------------
1 | import { Extension, Range } from "@tiptap/react";
2 | import { EditorState, Plugin, PluginKey, Transaction } from "prosemirror-state";
3 | import invariant from "tiny-invariant";
4 | import { AsyncQuery } from "../lib/AsyncQuery";
5 | import { computeChangedRanges } from "./computeChangedRanges";
6 |
7 | interface AsyncFlowPluginState {
8 | query: AsyncQuery;
9 | queryResult: null | string;
10 | }
11 |
12 | export const AsyncFlowExtension = Extension.create({
13 | name: "async-flow",
14 | addProseMirrorPlugins() {
15 | const self = this; // eslint-disable-line @typescript-eslint/no-this-alias
16 | return [
17 | new Plugin({
18 | key: new PluginKey(self.name),
19 | view(editor) {
20 | const pluginKey = this.key;
21 | invariant(pluginKey);
22 | return {
23 | update(editor, oldState) {
24 | const next = pluginKey.getState(editor.state);
25 | const prev = pluginKey.getState(oldState);
26 | const { query, queryResult } = next ?? {};
27 |
28 | // run the query update step
29 | query?.viewUpdate(editor, {
30 | ignoreCanceled: true,
31 | ignoreLoading: true,
32 | });
33 |
34 | // do something when the query data is loaded
35 | if (queryResult && queryResult !== prev?.queryResult) {
36 | console.log("query data loaded", queryResult);
37 | }
38 | },
39 | destroy() {
40 | // run the query destroy step
41 | pluginKey.getState(editor.state)?.query?.viewDestroy();
42 | },
43 | };
44 | },
45 | state: {
46 | init() {
47 | return {
48 | query: AsyncQuery.empty(),
49 | queryResult: null,
50 | };
51 | },
52 | apply(tr, prev, oldState, newState) {
53 | const { query: prevQuery } = prev;
54 | const pluginKey = this.spec.key;
55 | invariant(pluginKey);
56 |
57 | if (prevQuery.statusChanged(tr, "success")) {
58 | return {
59 | ...prev,
60 | queryResult: prevQuery.data!,
61 | };
62 | }
63 |
64 | // get query parameters from the transaction
65 | const newParameters = getTypedCharacter(newState, tr);
66 |
67 | // check if the query parameters have changed
68 | const changed = newParameters && prevQuery.parameters !== newParameters;
69 |
70 | if (!changed) {
71 | return prev;
72 | }
73 |
74 | const next = { ...prev };
75 |
76 | if (changed) {
77 | // cancel the previous query
78 | prevQuery.cancel();
79 |
80 | // create the new query
81 | const newQuery = new AsyncQuery({
82 | query: async () => {
83 | const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
84 | await delay(1000);
85 | return newParameters;
86 | },
87 | metaKey: pluginKey,
88 | parameters: newParameters,
89 | });
90 | next.query = newQuery;
91 | }
92 |
93 | return next;
94 | },
95 | },
96 | }),
97 | ];
98 | },
99 | });
100 |
101 | function getTypedCharacter(newState: EditorState, tr: Transaction) {
102 | const { empty, from, to } = newState.selection;
103 | const selectionRange: Range = { from, to };
104 | const changedRanges = computeChangedRanges(tr).changedRanges.filter((cr) => rangeIntersects(cr, selectionRange));
105 | if (empty && changedRanges.length > 0) {
106 | const changedText = tr.doc.textBetween(changedRanges[0].from, changedRanges[0].to);
107 | if (changedText.length > 0) {
108 | // TODO(lukemurray): this should return a string
109 | return changedText[changedText.length - 1];
110 | }
111 | }
112 | return null;
113 | }
114 |
115 | function rangeIntersects(a: Range, b: Range) {
116 | return a.from <= b.to && a.to >= b.from;
117 | }
118 |
--------------------------------------------------------------------------------
/src/LogsContainer.tsx:
--------------------------------------------------------------------------------
1 | import { Console, Hook, Unhook } from "console-feed";
2 | import { HookedConsole, Message } from "console-feed/lib/definitions/Console";
3 | import React, { useEffect, useState } from "react";
4 |
5 | export const LogsContainer = () => {
6 | const [logs, setLogs] = useState([]);
7 |
8 | // run once!
9 | useEffect(() => {
10 | Hook(window.console, (log) => setLogs((currLogs) => [...currLogs, log]), false);
11 | return () => {
12 | Unhook(window.console as HookedConsole);
13 | };
14 | }, []);
15 |
16 | return (
17 | <>
18 | Console
19 |
20 |
28 | {
31 | setLogs([]);
32 | }}
33 | >
34 | Clear Console
35 |
36 |
37 | );
38 | };
39 |
--------------------------------------------------------------------------------
/src/SandboxAsyncFlow.tsx:
--------------------------------------------------------------------------------
1 | import Document from "@tiptap/extension-document";
2 | import Paragraph from "@tiptap/extension-paragraph";
3 | import Text from "@tiptap/extension-text";
4 | import { EditorContent, useEditor } from "@tiptap/react";
5 | import React from "react";
6 | import { AsyncFlowExtension } from "./AsyncFlowExtension";
7 | import { LogsContainer } from "./LogsContainer";
8 |
9 | export const SandboxAsyncFlow = () => {
10 | const editor = useEditor({
11 | extensions: [Document, Paragraph, Text, AsyncFlowExtension],
12 | content: `This editor uses queries to implement async behavior. It uses promises to log the last character typed on a 1 second debounce.
`,
13 | });
14 |
15 | return (
16 |
17 |
Prosemirror Async Query
18 |
A simple declarative API for using promises in prosemirror plugin state.
19 |
20 | For more info, check the project out on{" "}
21 | github or{" "}
22 | npm .
23 |
24 |
25 |
26 |
27 |
8 | ,
10 | document.getElementById("root"),
11 | );
12 |
--------------------------------------------------------------------------------
/src/vite-env.d.ts:
--------------------------------------------------------------------------------
1 | ///