Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate API documentation via TypeDoc #821

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
+326 −7
Draft

Generate API documentation via TypeDoc #821

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 99 additions & 1 deletion packages/next-drupal/src/next-drupal-base.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ const DEFAULT_HEADERS = {
Accept: "application/json",
}

/**
* The base class for NextDrupal clients.
*/
export class NextDrupalBase {
accessToken?: NextDrupalBaseOptions["accessToken"]

Expand Down Expand Up @@ -173,6 +176,13 @@ export class NextDrupalBase {
return this._token
}

/**
* Fetches a resource from the given input URL or path.
*
* @param {RequestInfo} input The input URL or path.
* @param {FetchOptions} init The fetch options.
* @returns {Promise<Response>} The fetch response.
*/
async fetch(
input: RequestInfo,
{ withAuth, ...init }: FetchOptions = {}
Expand Down Expand Up @@ -215,6 +225,12 @@ export class NextDrupalBase {
return await fetch(input, init)
}

/**
* Gets the authorization header value based on the provided auth configuration.
*
* @param {NextDrupalAuth} auth The auth configuration.
* @returns {Promise<string>} The authorization header value.
*/
async getAuthorizationHeader(auth: NextDrupalAuth) {
let header: string

Expand Down Expand Up @@ -250,6 +266,13 @@ export class NextDrupalBase {
return header
}

/**
* Builds a URL with the given path and search parameters.
*
* @param {string} path The URL path.
* @param {EndpointSearchParams} searchParams The search parameters.
* @returns {URL} The constructed URL.
*/
buildUrl(path: string, searchParams?: EndpointSearchParams): URL {
const url = new URL(path, this.baseUrl)

Expand All @@ -269,7 +292,15 @@ export class NextDrupalBase {
return url
}

// async so subclasses can query for endpoint discovery.
/**
* Builds an endpoint URL with the given options.
*
* @param {Object} options The options for building the endpoint.
* @param {string} options.locale The locale.
* @param {string} options.path The path.
* @param {EndpointSearchParams} options.searchParams The search parameters.
* @returns {Promise<string>} The constructed endpoint URL.
*/
async buildEndpoint({
locale = "",
path = "",
Expand All @@ -291,6 +322,16 @@ export class NextDrupalBase {
).toString()
}

/**
* Constructs a path from the given segment and options.
*
* @param {string | string[]} segment The path segment.
* @param {Object} options The options for constructing the path.
* @param {Locale} options.locale The locale.
* @param {Locale} options.defaultLocale The default locale.
* @param {PathPrefix} options.pathPrefix The path prefix.
* @returns {string} The constructed path.
*/
constructPathFromSegment(
segment: string | string[],
options: {
Expand Down Expand Up @@ -338,6 +379,15 @@ export class NextDrupalBase {
})
}

/**
* Adds a locale prefix to the given path.
*
* @param {string} path The path.
* @param {Object} options The options for adding the locale prefix.
* @param {Locale} options.locale The locale.
* @param {Locale} options.defaultLocale The default locale.
* @returns {string} The path with the locale prefix.
*/
addLocalePrefix(
path: string,
options: { locale?: Locale; defaultLocale?: Locale } = {}
Expand All @@ -356,6 +406,12 @@ export class NextDrupalBase {
return `${localePrefix}${path}`
}

/**
* Gets an access token using the provided client ID and secret.
*
* @param {NextDrupalAuthClientIdSecret} clientIdSecret The client ID and secret.
* @returns {Promise<AccessToken>} The access token.
*/
async getAccessToken(
clientIdSecret?: NextDrupalAuthClientIdSecret
): Promise<AccessToken> {
Expand Down Expand Up @@ -435,6 +491,12 @@ export class NextDrupalBase {
return result
}

/**
* Validates the draft URL using the provided search parameters.
*
* @param {URLSearchParams} searchParams The search parameters.
* @returns {Promise<Response>} The validation response.
*/
async validateDraftUrl(searchParams: URLSearchParams): Promise<Response> {
const path = searchParams.get("path")

Expand Down Expand Up @@ -468,17 +530,35 @@ export class NextDrupalBase {
return response
}

/**
* Logs a debug message if debug mode is enabled.
*
* @param {string} message The debug message.
*/
debug(message) {
this.isDebugEnabled && this.logger.debug(message)
}

/**
* Throws an error if the response contains JSON:API errors.
*
* @param {Response} response The fetch response.
* @param {string} messagePrefix The error message prefix.
* @throws {JsonApiErrors} The JSON:API errors.
*/
async throwIfJsonErrors(response: Response, messagePrefix = "") {
if (!response?.ok) {
const errors = await this.getErrorsFromResponse(response)
throw new JsonApiErrors(errors, response.status, messagePrefix)
}
}

/**
* Extracts errors from the fetch response.
*
* @param {Response} response The fetch response.
* @returns {Promise<string | JsonApiResponse>} The extracted errors.
*/
async getErrorsFromResponse(response: Response) {
const type = response.headers.get("content-type")
let error: JsonApiResponse | { message: string }
Expand Down Expand Up @@ -506,6 +586,12 @@ export class NextDrupalBase {
}
}

/**
* Checks if the provided auth configuration is basic auth.
*
* @param {NextDrupalAuth} auth The auth configuration.
* @returns {boolean} True if the auth configuration is basic auth, false otherwise.
*/
export function isBasicAuth(
auth: NextDrupalAuth
): auth is NextDrupalAuthUsernamePassword {
Expand All @@ -515,6 +601,12 @@ export function isBasicAuth(
)
}

/**
* Checks if the provided auth configuration is access token auth.
*
* @param {NextDrupalAuth} auth The auth configuration.
* @returns {boolean} True if the auth configuration is access token auth, false otherwise.
*/
export function isAccessTokenAuth(
auth: NextDrupalAuth
): auth is NextDrupalAuthAccessToken {
Expand All @@ -524,6 +616,12 @@ export function isAccessTokenAuth(
)
}

/**
* Checks if the provided auth configuration is client ID and secret auth.
*
* @param {NextDrupalAuth} auth The auth configuration.
* @returns {boolean} True if the auth configuration is client ID and secret auth, false otherwise.
*/
export function isClientIdSecretAuth(
auth: NextDrupalAuth
): auth is NextDrupalAuthClientIdSecret {
Expand Down
91 changes: 91 additions & 0 deletions packages/next-drupal/src/next-drupal-pages.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ import type {
NextApiResponse,
} from "next"

/**
* The NextDrupalPages class extends the NextDrupal class and provides methods
* for interacting with a Drupal backend in the context of Next.js pages.
*/
export class NextDrupalPages extends NextDrupal {
private serializer: DrupalClientOptions["serializer"]

Expand Down Expand Up @@ -59,6 +63,13 @@ export class NextDrupalPages extends NextDrupal {
) => this.serializer.deserialize(body, options)
}

/**
* Gets the entry point for a given resource type.
*
* @param {string} resourceType The resource type.
* @param {Locale} locale The locale.
* @returns {Promise<string>} The entry point URL.
*/
async getEntryForResourceType(
resourceType: string,
locale?: Locale
Expand All @@ -74,6 +85,14 @@ export class NextDrupalPages extends NextDrupal {
return new DrupalMenuTree<DrupalMenuItem>(links, parent)
}

/**
* Gets a resource from the context.
*
* @param {string | DrupalTranslatedPath} input The input path or translated path.
* @param {GetStaticPropsContext} context The static props context.
* @param {Object} options Options for the request.
* @returns {Promise<T>} The fetched resource.
*/
async getResourceFromContext<T extends JsonApiResource>(
input: string | DrupalTranslatedPath,
context: GetStaticPropsContext,
Expand Down Expand Up @@ -157,6 +176,14 @@ export class NextDrupalPages extends NextDrupal {
return resource
}

/**
* Gets a collection of resources from the context.
*
* @param {string} type The type of the resources.
* @param {GetStaticPropsContext} context The static props context.
* @param {Object} options Options for the request.
* @returns {Promise<T>} The fetched collection of resources.
*/
async getResourceCollectionFromContext<T = JsonApiResource[]>(
type: string,
context: GetStaticPropsContext,
Expand All @@ -177,6 +204,14 @@ export class NextDrupalPages extends NextDrupal {
})
}

/**
* Gets a search index from the context.
*
* @param {string} name The name of the search index.
* @param {GetStaticPropsContext} context The static props context.
* @param {Object} options Options for the request.
* @returns {Promise<T>} The fetched search index.
*/
async getSearchIndexFromContext<T = JsonApiResource[]>(
name: string,
context: GetStaticPropsContext,
Expand All @@ -189,6 +224,13 @@ export class NextDrupalPages extends NextDrupal {
})
}

/**
* Translates a path from the context.
*
* @param {GetStaticPropsContext} context The static props context.
* @param {Object} options Options for the request.
* @returns {Promise<DrupalTranslatedPath | null>} The translated path.
*/
async translatePathFromContext(
context: GetStaticPropsContext,
options?: {
Expand All @@ -208,6 +250,13 @@ export class NextDrupalPages extends NextDrupal {
})
}

/**
* Gets the path from the context.
*
* @param {GetStaticPropsContext} context The static props context.
* @param {Object} options Options for the request.
* @returns {string} The constructed path.
*/
getPathFromContext(
context: GetStaticPropsContext,
options?: {
Expand All @@ -223,6 +272,14 @@ export class NextDrupalPages extends NextDrupal {

getPathsFromContext = this.getStaticPathsFromContext

/**
* Gets static paths from the context.
*
* @param {string | string[]} types The types of the resources.
* @param {GetStaticPathsContext} context The static paths context.
* @param {Object} options Options for the request.
* @returns {Promise<GetStaticPathsResult<{ slug: string[] }>["paths"]>} The fetched static paths.
*/
async getStaticPathsFromContext(
types: string | string[],
context: GetStaticPathsContext,
Expand Down Expand Up @@ -291,6 +348,13 @@ export class NextDrupalPages extends NextDrupal {
return paths.flat()
}

/**
* Builds static paths from resources.
*
* @param {Object[]} resources The resources.
* @param {Object} options Options for the request.
* @returns {Object[]} The built static paths.
*/
buildStaticPathsFromResources(
resources: {
path: DrupalPathAlias
Expand All @@ -313,6 +377,13 @@ export class NextDrupalPages extends NextDrupal {
: []
}

/**
* Builds static paths parameters from paths.
*
* @param {string[]} paths The paths.
* @param {Object} options Options for the request.
* @returns {Object[]} The built static paths parameters.
*/
buildStaticPathsParamsFromPaths(
paths: string[],
options?: { pathPrefix?: PathPrefix; locale?: Locale }
Expand Down Expand Up @@ -342,6 +413,13 @@ export class NextDrupalPages extends NextDrupal {
})
}

/**
* Handles preview mode.
*
* @param {NextApiRequest} request The API request.
* @param {NextApiResponse} response The API response.
* @param {Object} options Options for the request.
*/
async preview(
request: NextApiRequest,
response: NextApiResponse,
Expand Down Expand Up @@ -411,6 +489,12 @@ export class NextDrupalPages extends NextDrupal {
}
}

/**
* Disables preview mode.
*
* @param {NextApiRequest} request The API request.
* @param {NextApiResponse} response The API response.
*/
async previewDisable(request: NextApiRequest, response: NextApiResponse) {
// Disable both preview and draft modes.
response.clearPreviewData()
Expand All @@ -427,6 +511,13 @@ export class NextDrupalPages extends NextDrupal {
response.end()
}

/**
* Gets the authentication configuration from the context and options.
*
* @param {GetStaticPropsContext} context The static props context.
* @param {JsonApiWithAuthOption} options Options for the request.
* @returns {NextDrupalAuth} The authentication configuration.
*/
getAuthFromContextAndOptions(
context: GetStaticPropsContext,
options: JsonApiWithAuthOption
Expand Down
Loading
Loading