Skip to content

Commit

Permalink
feat!: flatten api (#10)
Browse files Browse the repository at this point in the history
  • Loading branch information
@achou11
achou11 authored Dec 16, 2024
1 parent 48fa389 commit a47d577
Show file tree
Hide file tree
Showing 8 changed files with 140 additions and 124 deletions.
50 changes: 24 additions & 26 deletions docs/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,37 +177,37 @@ function IsArchiveDeviceExample() {

| Function | Type |
| ---------- | ---------- |
| `getManyDocumentsQueryKey` | `<D extends DocumentType>({ projectId, docType, opts, }: { projectId: string; docType: D; opts?: Parameters<ClientApi<MapeoProject>[D]["getMany"]>[0] or undefined; }) => readonly [...]` |
| `getManyDocumentsQueryKey` | `<D extends DocumentType>({ projectId, docType, includeDeleted, lang, }: { projectId: string; docType: D; includeDeleted?: boolean or undefined; lang?: string or undefined; }) => readonly ["@comapeo/core-react", "projects", string, D, { ...; }]` |

### getDocumentByDocIdQueryKey

| Function | Type |
| ---------- | ---------- |
| `getDocumentByDocIdQueryKey` | `<D extends DocumentType>({ projectId, docType, docId, opts, }: { projectId: string; docType: D; docId: Parameters<ClientApi<MapeoProject>[D]["getByDocId"]>[0]; opts?: Parameters<ClientApi<MapeoProject>[D]["getByDocId"]>[1] or undefined; }) => readonly [...]` |
| `getDocumentByDocIdQueryKey` | `<D extends DocumentType>({ projectId, docType, docId, lang, }: { projectId: string; docType: D; docId: string; lang?: string or undefined; }) => readonly ["@comapeo/core-react", "projects", string, D, string, { readonly lang: string or undefined; }]` |

### getDocumentByVersionIdQueryKey

| Function | Type |
| ---------- | ---------- |
| `getDocumentByVersionIdQueryKey` | `<D extends DocumentType>({ projectId, docType, versionId, opts, }: { projectId: string; docType: D; versionId: Parameters<ClientApi<MapeoProject>[D]["getByVersionId"]>[0]; opts?: Parameters<ClientApi<...>[D]["getByVersionId"]>[1] or undefined; }) => readonly [...]` |
| `getDocumentByVersionIdQueryKey` | `<D extends DocumentType>({ projectId, docType, versionId, lang, }: { projectId: string; docType: D; versionId: string; lang?: string or undefined; }) => readonly ["@comapeo/core-react", "projects", string, D, string, { readonly lang: string or undefined; }]` |

### documentsQueryOptions

| Function | Type |
| ---------- | ---------- |
| `documentsQueryOptions` | `<D extends DocumentType>({ projectApi, projectId, docType, opts, }: { projectApi: ClientApi<MapeoProject>; projectId: string; docType: D; opts?: Parameters<ClientApi<MapeoProject>[D]["getMany"]>[0] or undefined; }) => OmitKeyof<...> and ... 1 more ... and { ...; }` |
| `documentsQueryOptions` | `<D extends DocumentType>({ projectApi, projectId, docType, includeDeleted, lang, }: { projectApi: ClientApi<MapeoProject>; projectId: string; docType: D; includeDeleted?: boolean or undefined; lang?: string or undefined; }) => OmitKeyof<...> and ... 1 more ... and { ...; }` |

### documentByDocumentIdQueryOptions

| Function | Type |
| ---------- | ---------- |
| `documentByDocumentIdQueryOptions` | `<D extends DocumentType>({ projectApi, projectId, docType, docId, opts, }: { projectApi: ClientApi<MapeoProject>; projectId: string; docType: D; docId: Parameters<ClientApi<MapeoProject>[D]["getByDocId"]>[0]; opts?: Omit<...> or undefined; }) => OmitKeyof<...> and ... 1 more ... and { ...; }` |
| `documentByDocumentIdQueryOptions` | `<D extends DocumentType>({ projectApi, projectId, docType, docId, lang, }: { projectApi: ClientApi<MapeoProject>; projectId: string; docType: D; docId: string; lang?: string or undefined; }) => OmitKeyof<UseQueryOptions<({ schemaName: "track"; ... 9 more ...; deleted: boolean; } and { ...; }) or ({ ...; } and { ...; }) or ...` |

### documentByVersionIdQueryOptions

| Function | Type |
| ---------- | ---------- |
| `documentByVersionIdQueryOptions` | `<D extends DocumentType>({ projectApi, projectId, docType, versionId, opts, }: { projectApi: ClientApi<MapeoProject>; projectId: string; docType: D; versionId: Parameters<ClientApi<MapeoProject>[D]["getByVersionId"]>[0]; opts?: Parameters<...>[1] or undefined; }) => OmitKeyof<...> and ... 1 more ... and { ...; }` |
| `documentByVersionIdQueryOptions` | `<D extends DocumentType>({ projectApi, projectId, docType, versionId, lang, }: { projectApi: ClientApi<MapeoProject>; projectId: string; docType: D; versionId: string; lang?: string or undefined; }) => OmitKeyof<UseQueryOptions<{ schemaName: "track"; ... 9 more ...; deleted: boolean; } or { ...; } or { ...; } or { ...; ...` |

### getProjectsQueryKey

Expand Down Expand Up @@ -249,7 +249,7 @@ function IsArchiveDeviceExample() {

| Function | Type |
| ---------- | ---------- |
| `getIconUrlQueryKey` | `({ projectId, iconId, opts, }: { projectId: string; iconId: string; opts: BitmapOpts or SvgOpts; }) => readonly ["@comapeo/core-react", "projects", string, "icons", string, BitmapOpts or SvgOpts]` |
| `getIconUrlQueryKey` | `({ projectId, iconId, ...mimeBasedOpts }: { projectId: string; iconId: string; } and (BitmapOpts or SvgOpts)) => readonly ["@comapeo/core-react", "projects", string, "icons", string, { mimeType: "image/png"; pixelDensity: 2 or ... 1 more ... or 1; size: ValidSizes; } or { ...; }]` |

### getDocumentCreatedByQueryKey

Expand Down Expand Up @@ -303,7 +303,7 @@ function IsArchiveDeviceExample() {

| Function | Type |
| ---------- | ---------- |
| `iconUrlQueryOptions` | `({ projectApi, projectId, iconId, opts, }: { projectApi: ClientApi<MapeoProject>; projectId: string; iconId: string; opts: BitmapOpts or SvgOpts; }) => OmitKeyof<UseQueryOptions<string, Error, string, QueryKey>, "queryFn"> and { ...; } and { ...; }` |
| `iconUrlQueryOptions` | `({ projectApi, projectId, iconId, ...mimeBasedOpts }: { projectApi: ClientApi<MapeoProject>; projectId: string; iconId: string; } and (BitmapOpts or SvgOpts)) => OmitKeyof<UseQueryOptions<string, Error, string, QueryKey>, "queryFn"> and { ...; } and { ...; }` |

### documentCreatedByQueryOptions

Expand Down Expand Up @@ -441,13 +441,15 @@ _TODO: Explain bitmap opts vs svg opts_

| Function | Type |
| ---------- | ---------- |
| `useIconUrl` | `({ projectId, iconId, opts, }: { projectId: string; iconId: string; opts: BitmapOpts or SvgOpts; }) => { data: string; error: Error or null; isRefetching: boolean; }` |
| `useIconUrl` | `({ projectId, iconId, ...mimeBasedOpts }: { projectId: string; iconId: string; } and (BitmapOpts or SvgOpts)) => { data: string; error: Error or null; isRefetching: boolean; }` |

Parameters:

* `opts.projectId`: Project public ID
* `opts.iconId`: Icon ID of interest
* `opts.opts`: Parameters related to the mime type of the icon of interest
* `opts.mimeType`: MIME type of desired resource
* `opts.pixelDensity`: Pixel density resource (only applicable when `mimeType` is `'image/png'`)
* `opts.size`: Size of desired resource


Examples:
Expand All @@ -457,11 +459,9 @@ function PngExample() {
const { data } = useIconUrl({
projectId: '...',
iconId: '...',
opts: {
mimeType: 'image/png',
pixelDensity: 1,
size: 'medium'
}
mimeType: 'image/png',
pixelDensity: 1,
size: 'medium'
})
}
```
Expand All @@ -471,10 +471,8 @@ function SvgExample() {
const { data } = useIconUrl({
projectId: '...',
iconId: '...',
opts: {
mimeType: 'image/svg',
size: 'medium'
}
mimeType: 'image/svg',
size: 'medium'
})
}
```
Expand Down Expand Up @@ -575,14 +573,14 @@ Triggers the closest error boundary if the document cannot be found

| Function | Type |
| ---------- | ---------- |
| `useSingleDocByDocId` | `<D extends DocumentType>({ projectId, docType, docId, opts, }: { projectId: string; docType: D; docId: string; opts?: Omit<{ mustBeFound?: boolean or undefined; lang?: string or undefined; } or undefined, "mustBeFound"> or undefined; }) => { ...; }` |
| `useSingleDocByDocId` | `<D extends DocumentType>({ projectId, docType, docId, lang, }: { projectId: string; docType: D; docId: string; lang?: string or undefined; }) => { data: ({ schemaName: "track"; locations: Position[]; observationRefs: { docId: string; versionId: string; }[]; ... 7 more ...; deleted: boolean; } and { ...; }) or ({ ...; } ...` |

Parameters:

* `opts.projectId`: Project public ID
* `opts.docType`: Document type of interest
* `opts.docId`: Document ID
* `opts.opts.lang`: Language to translate the document into
* `opts.lang`: Language to translate the document into


Examples:
Expand All @@ -608,14 +606,14 @@ Triggers the closest error boundary if the document cannot be found.

| Function | Type |
| ---------- | ---------- |
| `useSingleDocByVersionId` | `<D extends DocumentType>({ projectId, docType, versionId, opts, }: { projectId: string; docType: D; versionId: string; opts?: { lang?: string or undefined; } or undefined; }) => { data: { schemaName: "track"; locations: Position[]; ... 8 more ...; deleted: boolean; } or { ...; } or { ...; } or { ...; } or { ...; }; error:...` |
| `useSingleDocByVersionId` | `<D extends DocumentType>({ projectId, docType, versionId, lang, }: { projectId: string; docType: D; versionId: string; lang?: string or undefined; }) => { data: { schemaName: "track"; locations: Position[]; observationRefs: { ...; }[]; ... 7 more ...; deleted: boolean; } or { ...; } or { ...; } or { ...; } or { ...; }; e...` |

Parameters:

* `opts.projectId`: Project public ID
* `opts.docType`: Document type of interest
* `opts.versionId`: Document's version ID
* `opts.opts.lang`: Language to translate the document into
* `opts.lang`: Language to translate the document into

*

Expand All @@ -641,14 +639,14 @@ Retrieve all documents of a specific `docType`.

| Function | Type |
| ---------- | ---------- |
| `useManyDocs` | `<D extends DocumentType>({ projectId, docType, opts, }: { projectId: string; docType: D; opts?: { includeDeleted?: boolean or undefined; lang?: string or undefined; } or undefined; }) => { data: ({ schemaName: "track"; locations: Position[]; ... 8 more ...; deleted: boolean; } and { ...; })[] or ({ ...; } and { ...; })[] or ...` |
| `useManyDocs` | `<D extends DocumentType>({ projectId, docType, includeDeleted, lang, }: { projectId: string; docType: D; includeDeleted?: boolean or undefined; lang?: string or undefined; }) => { data: ({ schemaName: "track"; locations: Position[]; ... 8 more ...; deleted: boolean; } and { ...; })[] or ({ ...; } and { ...; })[] or ({ ...; ...` |

Parameters:

* `opts.projectId`: Project public ID
* `opts.docType`: Document type of interest
* `opts.opts.includeDeleted`: Include documents that have been marked as deleted
* `opts.opts.lang`: Language to translate the documents into
* `opts.includeDeleted`: Include documents that have been marked as deleted
* `opts.lang`: Language to translate the documents into


Examples:
Expand Down
2 changes: 1 addition & 1 deletion src/contexts/ClientApi.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ export const ClientApiContext = createContext<MapeoClientApi | null>(null)
/**
* Create a context provider that holds a CoMapeo API client instance.
*
* @param {Object} opts
* @param opts
* @param {ReactNode} opts.children React children node
* @param {MapeoClientApi} opts.clientApi Client API instance
*/
Expand Down
2 changes: 1 addition & 1 deletion src/hooks/client.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import {
* Access a client API instance. If a ClientApiContext provider is not
* set up, it will throw an error.
*
* @returns {import('@comapeo/ipc').MapeoClientApi} Client API instance
* @returns Client API instance
*
* @example
* ```tsx
Expand Down
51 changes: 24 additions & 27 deletions src/hooks/documents.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,10 @@ import { useSingleProject } from './projects'
*
* Triggers the closest error boundary if the document cannot be found
*
* @param {Object} opts
* @param {string} opts.projectId Project public ID
* @param {DocumentType} opts.docType Document type of interest
* @param {string} opts.docId Document ID
* @param {Object} [opts.opts]
* @param {string} [opts.opts.lang] Language to translate the document into
* @param opts.projectId Project public ID
* @param opts.docType Document type of interest
* @param opts.docId Document ID
* @param opts.lang Language to translate the document into
*
* @example
* ```tsx
Expand All @@ -38,12 +36,12 @@ export function useSingleDocByDocId<D extends DocumentType>({
projectId,
docType,
docId,
opts,
lang,
}: {
projectId: string
docType: D
docId: string
opts?: Parameters<typeof documentByDocumentIdQueryOptions>[0]['opts']
lang?: string
}) {
const { data: projectApi } = useSingleProject({ projectId })

Expand All @@ -53,7 +51,7 @@ export function useSingleDocByDocId<D extends DocumentType>({
projectId,
docType,
docId,
opts,
lang,
}),
)

Expand All @@ -66,12 +64,10 @@ export function useSingleDocByDocId<D extends DocumentType>({
*
* Triggers the closest error boundary if the document cannot be found.
*
* @param {Object} opts
* @param {string} opts.projectId Project public ID
* @param {DocumentType} opts.docType Document type of interest
* @param {string} opts.versionId Document's version ID
* @param {Object} [opts.opts]
* @param {string} [opts.opts.lang] Language to translate the document into
* @param opts.projectId Project public ID
* @param opts.docType Document type of interest
* @param opts.versionId Document's version ID
* @param opts.lang Language to translate the document into
*
* * @example
* ```tsx
Expand All @@ -90,12 +86,12 @@ export function useSingleDocByVersionId<D extends DocumentType>({
projectId,
docType,
versionId,
opts,
lang,
}: {
projectId: string
docType: D
versionId: string
opts?: Parameters<typeof documentByVersionIdQueryOptions>[0]['opts']
lang?: string
}) {
const { data: projectApi } = useSingleProject({ projectId })

Expand All @@ -105,7 +101,7 @@ export function useSingleDocByVersionId<D extends DocumentType>({
projectId,
docType,
versionId,
opts,
lang,
}),
)

Expand All @@ -116,12 +112,10 @@ export function useSingleDocByVersionId<D extends DocumentType>({
/**
* Retrieve all documents of a specific `docType`.
*
* @param {Object} opts
* @param {string} opts.projectId Project public ID
* @param {DocumentType} opts.docType Document type of interest
* @param {Object} [opts.opts]
* @param {boolean} [opts.opts.includeDeleted] Include documents that have been marked as deleted
* @param {string} [opts.opts.lang] Language to translate the documents into
* @param opts.projectId Project public ID
* @param opts.docType Document type of interest
* @param opts.includeDeleted Include documents that have been marked as deleted
* @param opts.lang Language to translate the documents into
*
* @example
* ```tsx
Expand Down Expand Up @@ -152,11 +146,13 @@ export function useSingleDocByVersionId<D extends DocumentType>({
export function useManyDocs<D extends DocumentType>({
projectId,
docType,
opts,
includeDeleted,
lang,
}: {
projectId: string
docType: D
opts?: Parameters<typeof documentsQueryOptions>[0]['opts']
includeDeleted?: boolean
lang?: string
}) {
const { data: projectApi } = useSingleProject({ projectId })

Expand All @@ -165,7 +161,8 @@ export function useManyDocs<D extends DocumentType>({
projectApi,
projectId,
docType,
opts,
includeDeleted,
lang,
}),
)

Expand Down
3 changes: 1 addition & 2 deletions src/hooks/maps.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ import { useClientApi } from './client'
* If `opts.refreshToken` is specified, it will be appended to the returned URL as a search param. This is useful for forcing cache busting
* due to hidden internal details by consuming components (e.g. map component from MapLibre).
*
* @param {Object} opts
* @param {string} opts.refreshToken String to append to the returned value as a search param
* @param opts.refreshToken String to append to the returned value as a search param
*
* @example
* ```tsx
Expand Down
Loading

0 comments on commit a47d577

Please sign in to comment.