From 0b1a610197e23c2462f62443497c7044d7f49ccf Mon Sep 17 00:00:00 2001 From: lihbr Date: Mon, 16 Aug 2021 10:19:33 +0200 Subject: [PATCH] docs: add tsdocs for hooks --- src/hooks.ts | 194 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) diff --git a/src/hooks.ts b/src/hooks.ts index 7672962..5c3eab0 100644 --- a/src/hooks.ts +++ b/src/hooks.ts @@ -10,11 +10,37 @@ import { const proto = prismic.Client.prototype; +/** + * A hook that queries content from the Prismic repository. + * + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.get} + */ export const usePrismicDocuments = ( ...args: [params?: ClientMethodParameters<"get">[0] & HookOnlyParameters] ): ClientHookReturnType> => useStatefulPrismicClientMethod(proto.get, args); +/** + * A hook that queries content from the Prismic repository and returns only the first result, if any. + * + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of the Prismic document returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getFirst} + */ export const useFirstPrismicDocument = < TDocument extends prismicT.PrismicDocument, >( @@ -22,6 +48,19 @@ export const useFirstPrismicDocument = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getFirst, args); +/** + * A hook that queries content from the Prismic repository and returns all matching content. If no predicates are provided, all documents will be fetched. + * + * @param params - Parameters to filter and sort results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getAll} + */ export const useAllPrismicDocuments = < TDocument extends prismicT.PrismicDocument, >( @@ -29,6 +68,20 @@ export const useAllPrismicDocuments = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getAll, args); +/** + * A hook that queries a document from the Prismic repository with a specific ID. + * + * @param id - ID of the document + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of the Prismic document returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getByID} + */ export const usePrismicDocumentByID = < TDocument extends prismicT.PrismicDocument, >( @@ -39,6 +92,20 @@ export const usePrismicDocumentByID = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getByID, args); +/** + * A hook that queries documents from the Prismic repository with specific IDs. + * + * @param ids - A list of document IDs + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getByIDs} + */ export const usePrismicDocumentsByIDs = < TDocument extends prismicT.PrismicDocument, >( @@ -49,6 +116,20 @@ export const usePrismicDocumentsByIDs = < ): ClientHookReturnType> => useStatefulPrismicClientMethod(proto.getByIDs, args); +/** + * A hook that queries all documents from the Prismic repository with specific IDs. + * + * @param ids - A list of document IDs + * @param params - Parameters to filter and sort results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getAllByIDs} + */ export const useAllPrismicDocumentsByIDs = < TDocument extends prismicT.PrismicDocument, >( @@ -59,6 +140,21 @@ export const useAllPrismicDocumentsByIDs = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getAllByIDs, args); +/** + * A hook that queries a document from the Prismic repository with a specific UID and Custom Type. + * + * @param documentType - The API ID of the document's Custom Type + * @param uid - UID of the document + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of the Prismic document returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getByUID} + */ export const usePrismicDocumentByUID = < TDocument extends prismicT.PrismicDocument, >( @@ -70,6 +166,20 @@ export const usePrismicDocumentByUID = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getByUID, args); +/** + * A hook that queries a singleton document from the Prismic repository for a specific Custom Type. + * + * @param documentType - The API ID of the singleton Custom Type + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of the Prismic document returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getSingle} + */ export const useSinglePrismicDocument = < TDocument extends prismicT.PrismicDocument, >( @@ -80,6 +190,20 @@ export const useSinglePrismicDocument = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getSingle, args); +/** + * A hook that queries documents from the Prismic repository for a specific Custom Type. + * + * @param documentType - The API ID of the Custom Type + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getByType} + */ export const usePrismicDocumentsByType = < TDocument extends prismicT.PrismicDocument, >( @@ -90,6 +214,20 @@ export const usePrismicDocumentsByType = < ): ClientHookReturnType> => useStatefulPrismicClientMethod(proto.getByType, args); +/** + * A hook that queries all documents from the Prismic repository for a specific Custom Type. + * + * @param documentType - The API ID of the Custom Type + * @param params - Parameters to filter and sort results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getAllByType} + */ export const useAllPrismicDocumentsByType = < TDocument extends prismicT.PrismicDocument, >( @@ -100,6 +238,20 @@ export const useAllPrismicDocumentsByType = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getAllByType, args); +/** + * A hook that queries documents from the Prismic repository with a specific tag. + * + * @param tag - The tag that must be included on a document + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getByTag} + */ export const usePrismicDocumentsByTag = < TDocument extends prismicT.PrismicDocument, >( @@ -110,6 +262,20 @@ export const usePrismicDocumentsByTag = < ): ClientHookReturnType> => useStatefulPrismicClientMethod(proto.getByTag, args); +/** + * A hook that queries all documents from the Prismic repository with a specific tag. + * + * @param tag - The tag that must be included on a document + * @param params - Parameters to filter and sort results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getAllByTag} + */ export const useAllPrismicDocumentsByTag = < TDocument extends prismicT.PrismicDocument, >( @@ -120,6 +286,20 @@ export const useAllPrismicDocumentsByTag = < ): ClientHookReturnType => useStatefulPrismicClientMethod(proto.getAllByTag, args); +/** + * A hook that queries documents from the Prismic repository with specific tags. + * + * @param tags - A list of tags that must be included on a document + * @param params - Parameters to filter, sort, and paginate results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getByTags} + */ export const usePrismicDocumentsByTags = < TDocument extends prismicT.PrismicDocument, >( @@ -130,6 +310,20 @@ export const usePrismicDocumentsByTags = < ): ClientHookReturnType> => useStatefulPrismicClientMethod(proto.getByTags, args); +/** + * A hook that queries all documents from the Prismic repository with specific tags. + * + * @param tags - A list of tags that must be included on a document + * @param params - Parameters to filter and sort results + * + * @returns The composable payload {@link ClientHookReturnType} + * + * @typeParam TDocument - Type of Prismic documents returned + * + * @remarks An additional `@prismicio/client` instance can be provided at `params.client`. + * + * @see Underlying `@prismicio/client` method {@link proto.getAllByTags} + */ export const useAllPrismicDocumentsByTags = < TDocument extends prismicT.PrismicDocument, >(