feat!: implement write hooks for documents

docs/API.md

@@ -23,6 +23,9 @@
 - [useSingleDocByDocId](#usesingledocbydocid)
 - [useSingleDocByVersionId](#usesingledocbyversionid)
 - [useManyDocs](#usemanydocs)
+- [useCreateDocument](#usecreatedocument)
+- [useUpdateDocument](#useupdatedocument)
+- [useDeleteDocument](#usedeletedocument)
 - [useAcceptInvite](#useacceptinvite)
 - [useRejectInvite](#userejectinvite)
 - [useSendInvite](#usesendinvite)
@@ -439,7 +442,7 @@ Triggers the closest error boundary if the document cannot be found
 
 | Function | Type |
 | ---------- | ---------- |
-| `useSingleDocByDocId` | `<D extends DocumentType>({ projectId, docType, docId, lang, }: { projectId: string; docType: D; docId: string; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ... 7 more ...; deleted: boolean; }...` |
+| `useSingleDocByDocId` | `<D extends WriteableDocumentType>({ projectId, docType, docId, lang, }: { projectId: string; docType: D; docId: string; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ... 7 more ...; deleted: b...` |
 
 Parameters:
 
@@ -472,7 +475,7 @@ Triggers the closest error boundary if the document cannot be found.
 
 | Function | Type |
 | ---------- | ---------- |
-| `useSingleDocByVersionId` | `<D extends DocumentType>({ projectId, docType, versionId, lang, }: { projectId: string; docType: D; versionId: string; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ... 7 more ...; deleted: bo...` |
+| `useSingleDocByVersionId` | `<D extends WriteableDocumentType>({ projectId, docType, versionId, lang, }: { projectId: string; docType: D; versionId: string; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ... 7 more ...; de...` |
 
 Parameters:
 
@@ -505,7 +508,7 @@ Retrieve all documents of a specific `docType`.
 
 | Function | Type |
 | ---------- | ---------- |
-| `useManyDocs` | `<D extends DocumentType>({ projectId, docType, includeDeleted, lang, }: { projectId: string; docType: D; includeDeleted?: boolean or undefined; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ......` |
+| `useManyDocs` | `<D extends WriteableDocumentType>({ projectId, docType, includeDeleted, lang, }: { projectId: string; docType: D; includeDeleted?: boolean or undefined; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNI...` |
 
 Parameters:
 
@@ -543,6 +546,48 @@ function useAllPresets(opts) {
 ```
 
 
+### useCreateDocument
+
+Create a document for a project.
+
+| Function | Type |
+| ---------- | ---------- |
+| `useCreateDocument` | `<D extends WriteableDocumentType>({ docType, projectId, }: { docType: D; projectId: string; }) => { mutate: UseMutateFunction<WriteableDocument<D> and { forks: string[]; }, Error, { value: Omit<WriteableValue<D>, "schemaName">; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }` |
+
+Parameters:
+
+* `opts.docType`: Document type to create.
+* `opts.projectId`: Public ID of project to create document for.
+
+
+### useUpdateDocument
+
+Update a document within a project.
+
+| Function | Type |
+| ---------- | ---------- |
+| `useUpdateDocument` | `<D extends WriteableDocumentType>({ docType, projectId, }: { docType: D; projectId: string; }) => { mutate: UseMutateFunction<WriteableDocument<D> and { forks: string[]; }, Error, { versionId: string; value: Omit<...>; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }` |
+
+Parameters:
+
+* `opts.docType`: Document type to update.
+* `opts.projectId`: Public ID of project document belongs to.
+
+
+### useDeleteDocument
+
+Delete a document within a project.
+
+| Function | Type |
+| ---------- | ---------- |
+| `useDeleteDocument` | `<D extends WriteableDocumentType>({ docType, projectId, }: { docType: D; projectId: string; }) => { mutate: UseMutateFunction<WriteableDocument<D> and { forks: string[]; }, Error, { docId: string; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }` |
+
+Parameters:
+
+* `opts.docType`: Document type to delete.
+* `opts.projectId`: Public ID of project document belongs to.
+
+
 ### useAcceptInvite
 
 Accept an invite that has been received.

src/hooks/documents.ts

@@ -1,11 +1,18 @@
 import type { MapeoDoc } from '@comapeo/schema' with { 'resolution-mode': 'import' }
-import { useSuspenseQuery } from '@tanstack/react-query'
+import {
+	useMutation,
+	useQueryClient,
+	useSuspenseQuery,
+} from '@tanstack/react-query'
 
 import {
+	createDocumentMutationOptions,
+	deleteDocumentMutationOptions,
 	documentByDocumentIdQueryOptions,
 	documentByVersionIdQueryOptions,
 	documentsQueryOptions,
-	type DocumentType,
+	updateDocumentMutationOptions,
+	type WriteableDocumentType,
 } from '../lib/react-query/documents.js'
 import { useSingleProject } from './projects.js'
 
@@ -38,7 +45,7 @@ type ReadHookResult<D> = {
  * }
  * ```
  */
-export function useSingleDocByDocId<D extends DocumentType>({
+export function useSingleDocByDocId<D extends WriteableDocumentType>({
 	projectId,
 	docType,
 	docId,
@@ -94,7 +101,7 @@ export function useSingleDocByDocId<D extends DocumentType>({
  * }
  * ```
  */
-export function useSingleDocByVersionId<D extends DocumentType>({
+export function useSingleDocByVersionId<D extends WriteableDocumentType>({
 	projectId,
 	docType,
 	versionId,
@@ -159,7 +166,7 @@ export function useSingleDocByVersionId<D extends DocumentType>({
  * }
  * ```
  */
-export function useManyDocs<D extends DocumentType>({
+export function useManyDocs<D extends WriteableDocumentType>({
 	projectId,
 	docType,
 	includeDeleted,
@@ -189,3 +196,87 @@ export function useManyDocs<D extends DocumentType>({
 		isRefetching,
 	}
 }
+
+/**
+ * Create a document for a project.
+ *
+ * @param opts.docType Document type to create.
+ * @param opts.projectId Public ID of project to create document for.
+ */
+export function useCreateDocument<D extends WriteableDocumentType>({
+	docType,
+	projectId,
+}: {
+	docType: D
+	projectId: string
+}) {
+	const queryClient = useQueryClient()
+	const { data: projectApi } = useSingleProject({ projectId })
+
+	const { mutate, reset, status } = useMutation(
+		createDocumentMutationOptions({
+			docType,
+			projectApi,
+			projectId,
+			queryClient,
+		}),
+	)
+
+	return { mutate, reset, status }
+}
+
+/**
+ * Update a document within a project.
+ *
+ * @param opts.docType Document type to update.
+ * @param opts.projectId Public ID of project document belongs to.
+ */
+export function useUpdateDocument<D extends WriteableDocumentType>({
+	docType,
+	projectId,
+}: {
+	docType: D
+	projectId: string
+}) {
+	const queryClient = useQueryClient()
+	const { data: projectApi } = useSingleProject({ projectId })
+
+	const { mutate, reset, status } = useMutation(
+		updateDocumentMutationOptions({
+			docType,
+			projectApi,
+			projectId,
+			queryClient,
+		}),
+	)
+
+	return { mutate, reset, status }
+}
+
+/**
+ * Delete a document within a project.
+ *
+ * @param opts.docType Document type to delete.
+ * @param opts.projectId Public ID of project document belongs to.
+ */
+export function useDeleteDocument<D extends WriteableDocumentType>({
+	docType,
+	projectId,
+}: {
+	docType: D
+	projectId: string
+}) {
+	const queryClient = useQueryClient()
+	const { data: projectApi } = useSingleProject({ projectId })
+
+	const { mutate, reset, status } = useMutation(
+		deleteDocumentMutationOptions({
+			docType,
+			projectApi,
+			projectId,
+			queryClient,
+		}),
+	)
+
+	return { mutate, reset, status }
+}

src/index.ts

@@ -7,9 +7,12 @@ export {
 	useSetOwnDeviceInfo,
 } from './hooks/client.js'
 export {
+	useCreateDocument,
+	useDeleteDocument,
 	useManyDocs,
 	useSingleDocByDocId,
 	useSingleDocByVersionId,
+	useUpdateDocument,
 } from './hooks/documents.js'
 export {
 	useAcceptInvite,
@@ -44,7 +47,9 @@ export {
 	getDocumentByVersionIdQueryKey,
 	getDocumentsQueryKey,
 	getManyDocumentsQueryKey,
-	type DocumentType,
+	type WriteableDocument,
+	type WriteableDocumentType,
+	type WriteableValue,
 } from './lib/react-query/documents.js'
 export {
 	getInvitesQueryKey,