asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(types): add TSDocs to the user module's types (#7549)

Browse Source
This commit is contained in:
Shahed Nasser
2024-05-30 18:04:44 +03:00
committed by GitHub
parent 22891060f9
commit 6b86b1d531
4 changed files with 393 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
packages/core/types/src/user/common.ts
View File

@@ -11,34 +11,42 @@ export interface UserDTO {
* The ID of the user.
*/
id: string
/**
* The email of the user.
*/
email: string
/**
* The first name of the user.
*/
first_name: string | null
/**
* The last name of the user.
*/
last_name: string | null
/**
* The avatar URL of the user.
*/
avatar_url: string | null
/**
* Holds custom data in key-value pairs.
*/
metadata: Record<string, unknown> | null
/**
* The creation date of the user.
*/
created_at: Date
/**
* The updated date of the user.
*/
updated_at: Date
/**
* The deletion date of the user.
*/
@@ -56,39 +64,95 @@ export interface FilterableUserProps
* Find users by name or email through this search term
*/
q?: string
/**
* The IDs to filter users by.
*/
id?: string | string[]
/**
* Filter users by their email.
*/
email?: string | string[]
/**
* Filter users by their first name.
*/
first_name?: string | string[]
/**
* Filter users by their last name.
*/
last_name?: string | string[]
}
/**
* The invite details.
*/
export interface InviteDTO {
/**
* The ID of the invite.
*/
id: string
/**
* The email of the invite.
*/
email: string
/**
* Whether the invite is accepted.
*/
accepted: boolean
/**
* The token of the invite.
*/
token: string
/**
* The invite's expiry date.
*/
expires_at: Date
/**
* Holds custom data in key-value pairs.
*/
metadata: Record<string, unknown> | null
/**
* The invite's creation date.
*/
created_at: Date
/**
* The invite's update date.
*/
updated_at: Date
/**
* The invite's deletion date.
*/
deleted_at: Date | null
}
/**
* The filters to apply on the retrieved invites.
*/
export interface FilterableInviteProps
extends BaseFilterable<FilterableInviteProps> {
/**
* The IDs to filter the invites by.
*/
id?: string | string[]
/**
* Filter the invites by their email.
*/
email?: string | string[]
/**
* Filter the invites by their expiry date.
*/
expires_at?: DateComparisonOperator
}

24
packages/core/types/src/user/mutations.ts
View File

@@ -6,18 +6,22 @@ export interface CreateUserDTO {
* The email of the user.
*/
email: string
/**
* The first name of the user.
*/
first_name?: string | null
/**
* The last name of the user.
*/
last_name?: string | null
/**
* The avatar URL of the user.
*/
avatar_url?: string | null
/**
* Holds custom data in key-value pairs.
*/
@@ -34,13 +38,33 @@ export interface UpdateUserDTO extends Partial<Omit<CreateUserDTO, "email">> {
id: string
}
/**
* The invite to be created.
*/
export interface CreateInviteDTO {
/**
* The email of the invite.
*/
email: string
/**
* Whether the invite is accepted.
*/
accepted?: boolean
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown> | null
}
/**
* The attributes to update in the invite.
*/
export interface UpdateInviteDTO
extends Partial<Omit<CreateInviteDTO, "email">> {
/**
* The ID of the invite.
*/
id: string
}

358
packages/core/types/src/user/service.ts
View File

@@ -6,27 +6,46 @@ import {
} from "./mutations"
import { FilterableUserProps, InviteDTO, UserDTO } from "./common"
import { RestoreReturn, SoftDeleteReturn } from "../dal"
import { Context } from "../shared-context"
import { FindConfig } from "../common"
import { IModuleService } from "../modules-sdk"
/**
* The main service interface for the user module.
* The main service interface for the User Module.
*/
export interface IUserModuleService extends IModuleService {
/**
* This method validates an invite token.
* This method validates that a token belongs to an invite and returns that invite.
*
* An error is thrown if the invite has expired or no invite matches the token.
*
* @param {string} token - The token to validate.
* @param {string} token - The token to validate
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO>} The associated invite's details.
* @returns {Promise<InviteDTO>} The token's invite.
*
* @example
* const invite = await userModuleService.validateInviteToken(
* "eyJhbG..."
* )
*/
validateInviteToken(
token: string,
sharedContext?: Context
): Promise<InviteDTO>
/**
* This method updates the token and expiration date of invites.
*
* @param {string[]} inviteIds - The IDs of the invites to refresh.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO[]>} The updated invites.
*
* @example
* const invites = await userModuleService.refreshInviteTokens([
* "invite_123",
* "invite_321"
* ])
*/
refreshInviteTokens(
inviteIds: string[],
sharedContext?: Context
@@ -35,26 +54,14 @@ export interface IUserModuleService extends IModuleService {
/**
* This method retrieves a user by its ID.
*
* @param {string} id - The ID of the retrieve.
* @param {string} id - The ID of the user.
* @param {FindConfig<UserDTO>} config - The configurations determining how the user is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<UserDTO>} The retrieved user.
*
* @example
* A simple example that retrieves a {type name} by its ID:
*
* ```ts
* {example-code}
* ```
*
* To specify relations that should be retrieved:
*
* ```ts
* {example-code}
* ```
*
*
* const user = await userModuleService.retrieve("user_123")
*/
retrieve(
id: string,
@@ -65,32 +72,34 @@ export interface IUserModuleService extends IModuleService {
/**
* This method retrieves a paginated list of users based on optional filters and configuration.
*
* @param {FilterableUserProps} filters - The filters to apply on the retrieved user.
* @param {FilterableUserProps} filters - The filters to apply on the retrieved users.
* @param {FindConfig<UserDTO>} config - The configurations determining how the user is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<UserDTO[]>} The list of users.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of users using their IDs:
*
* ```ts
* {example-code}
* const users = await userModuleService.list({
* id: ["user_123", "user_321"]
* })
* ```
*
* To specify relations that should be retrieved within the {type name}:
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* const users = await userModuleService.list(
* {
* id: ["user_123", "user_321"]
* },
* {
* take: 20,
* skip: 2
* }
* )
* ```
*
* By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* ```
*
*
*/
list(
filters?: FilterableUserProps,
@@ -99,34 +108,36 @@ export interface IUserModuleService extends IModuleService {
): Promise<UserDTO[]>
/**
* This method retrieves a paginated list of user along with the total count of available users satisfying the provided filters.
* This method retrieves a paginated list of users along with the total count of available users satisfying the provided filters.
*
* @param {FilterableUserProps} filters - The filters to apply on the retrieved user.
* @param {FilterableUserProps} filters - The filters to apply on the retrieved users.
* @param {FindConfig<UserDTO>} config - The configurations determining how the user is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<[UserDTO[], number]>} The list of users along with their total count.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of users using their IDs:
*
* ```ts
* {example-code}
* const [users, count] = await userModuleService.listAndCount({
* id: ["user_123", "user_321"]
* })
* ```
*
* To specify relations that should be retrieved within the {type name}:
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* const [users, count] = await userModuleService.listAndCount(
* {
* id: ["user_123", "user_321"]
* },
* {
* take: 20,
* skip: 2
* }
* )
* ```
*
* By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* ```
*
*
*/
listAndCount(
filters?: FilterableUserProps,
@@ -142,7 +153,14 @@ export interface IUserModuleService extends IModuleService {
* @returns {Promise<UserDTO[]>} The created users.
*
* @example
* {example-code}
* const users = await userModuleService.create([
* {
* email: "john@doe.com"
* },
* {
* email: "john2@doe.com"
* }
* ])
*/
create(data: CreateUserDTO[], sharedContext?: Context): Promise<UserDTO[]>
@@ -154,19 +172,30 @@ export interface IUserModuleService extends IModuleService {
* @returns {Promise<UserDTO>} The created user.
*
* @example
* {example-code}
* const user = await userModuleService.create({
* email: "john@doe.com"
* })
*/
create(data: CreateUserDTO, sharedContext?: Context): Promise<UserDTO>
/**
* This method updates existing users.
*
* @param {UpdateUserDTO[]} data - The attributes to update in each user.
* @param {UpdateUserDTO[]} data - The attributes to update in the users.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<UserDTO[]>} The updated users.
*
* @example
* {example-code}
* const users = await userModuleService.update([
* {
* id: "user_123",
* first_name: "John"
* },
* {
* id: "user_321",
* last_name: "Doe"
* }
* ])
*/
update(data: UpdateUserDTO[], sharedContext?: Context): Promise<UserDTO[]>
@@ -178,80 +207,301 @@ export interface IUserModuleService extends IModuleService {
* @returns {Promise<UserDTO>} The updated user.
*
* @example
* {example-code}
* const user = await userModuleService.update({
* id: "user_123",
* first_name: "John"
* })
*/
update(data: UpdateUserDTO, sharedContext?: Context): Promise<UserDTO>
/**
* This method deletes users by their IDs.
*
* @param {string[]} ids - The list of IDs of users to delete.
* @param {string[]} ids - The IDs of the users.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the users are deleted.
* @returns {Promise<void>} Resolves when the users are deleted successfully.
*
* @example
* {example-code}
* await userModuleService.delete([
* "user_123", "user_321"
* ])
*/
delete(ids: string[], sharedContext?: Context): Promise<void>
/**
* This method soft deletes a user by its IDs.
*
* @param {string[]} userIds - The IDs of users to soft-delete
* @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were also soft deleted.
* If there are no related records, the promise resolves to `void`.
*
* @example
* await userModuleService.softDelete([
* "user_123", "user_321"
* ])
*/
softDelete<TReturnableLinkableKeys extends string = string>(
userIds: string[],
config?: SoftDeleteReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<TReturnableLinkableKeys, string[]> | void>
/**
* This method restores soft deleted users by their IDs.
*
* @param {string[]} userIds - The IDs of users to restore.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the users. You can pass to its `returnLinkableKeys`
* property any of the user's relation attribute names.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored.
*
* If there are no related records restored, the promise resolves to `void`.
*
* @example
* await userModuleService.restore([
* "user_123", "user_321"
* ])
*/
restore<TReturnableLinkableKeys extends string = string>(
userIds: string[],
config?: RestoreReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<TReturnableLinkableKeys, string[]> | void>
/**
* This method retrieves an invite by its ID.
*
* @param {string} id - The ID of the invite.
* @param {FindConfig<InviteDTO>} config - The configurations determining how the invite is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a invite.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO>} The retrieved invite.
*
* @example
* const invite = await userModuleService.retrieveInvite(
* "invite_123"
* )
*/
retrieveInvite(
id: string,
config?: FindConfig<InviteDTO>,
sharedContext?: Context
): Promise<InviteDTO>
/**
* This method retrieves a paginated list of invites based on optional filters and configuration.
*
* @param {FilterableUserProps} filters - The filters to apply on the retrieved invites.
* @param {FindConfig<InviteDTO>} config - The configurations determining how the invite is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a invite.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO[]>} The list of invites.
*
* @example
* To retrieve a list of invites using their IDs:
*
* ```ts
* const invites = await userModuleService.listInvites({
* id: ["invite_123", "invite_321"]
* })
* ```
*
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* const invites = await userModuleService.listInvites(
* {
* id: ["invite_123", "invite_321"]
* },
* {
* take: 20,
* skip: 2
* }
* )
* ```
*/
listInvites(
filters?: FilterableUserProps,
config?: FindConfig<InviteDTO>,
sharedContext?: Context
): Promise<InviteDTO[]>
/**
* This method retrieves a paginated list of invites along with the total count of available invites satisfying the provided filters.
*
* @param {FilterableUserProps} filters - The filters to apply on the retrieved invites.
* @param {FindConfig<InviteDTO>} config - The configurations determining how the invite is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a invite.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<[InviteDTO[], number]>} The list of invites along with their total count.
*
* @example
* To retrieve a list of invites using their IDs:
*
* ```ts
* const [invites, count] = await userModuleService
* .listAndCountInvites({
* id: ["invite_123", "invite_321"]
* })
* ```
*
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* const [invites, count] = await userModuleService
* .listAndCountInvites(
* {
* id: ["invite_123", "invite_321"]
* },
* {
* take: 20,
* skip: 2
* }
* )
* ```
*/
listAndCountInvites(
filters?: FilterableUserProps,
config?: FindConfig<InviteDTO>,
sharedContext?: Context
): Promise<[InviteDTO[], number]>
/**
* This method creates invites.
*
* @param {CreateInviteDTO[]} data - The invites to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO[]>} The created invites.
*
* @example
* const invites = await userModuleService.createInvites([
* {
* email: "john@doe.com"
* },
* {
* email: "john2@doe.com"
* }
* ])
*/
createInvites(
data: CreateInviteDTO[],
sharedContext?: Context
): Promise<InviteDTO[]>
/**
* This method creates a invite.
*
* @param {CreateInviteDTO} data - The invite to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO>} The created invite.
*
* @example
* const invite = await userModuleService.createInvites({
* email: "john@doe.com"
* })
*/
createInvites(
data: CreateInviteDTO,
sharedContext?: Context
): Promise<InviteDTO>
/**
* This method updates existing invites.
*
* @param {UpdateInviteDTO[]} data - The attributes to update in the invites.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO[]>} The updated invites.
*
* @example
* const invites = await userModuleService.updateInvites([
* {
* id: "invite_123",
* accepted: true
* },
* {
* id: "invite_321",
* metadata: {
* test: true
* }
* }
* ])
*/
updateInvites(
data: UpdateInviteDTO[],
sharedContext?: Context
): Promise<InviteDTO[]>
/**
* This method updates an existing invite.
*
* @param {UpdateInviteDTO} data - The attributes to update in the invite.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<InviteDTO>} The updated invite.
*
* @example
* const invite = await userModuleService.updateInvites({
* id: "invite_123",
* accepted: true
* })
*/
updateInvites(
data: UpdateInviteDTO,
sharedContext?: Context
): Promise<InviteDTO>
/**
* This method deletes invites by their IDs.
*
* @param {string[]} ids - The IDs of the invites.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the invites are deleted successfully.
*
* @example
* await userModuleService.deleteInvites([
* "invite_123", "invite_321"
* ])
*/
deleteInvites(ids: string[], sharedContext?: Context): Promise<void>
/**
* This method soft deletes invites by their IDs.
*
* @param {string[]} inviteIds - The IDs of the invites to soft-delete.
* @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were also soft deleted.
*
* If there are no related records, the promise resolves to `void`.
*
* @example
* await userModuleService.softDeleteInvites([
* "invite_123", "invite_321"
* ])
*/
softDeleteInvites<TReturnableLinkableKeys extends string = string>(
inviteIds: string[],
config?: SoftDeleteReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<TReturnableLinkableKeys, string[]> | void>
/**
* This method restores soft deleted invites by their IDs.
*
* @param {string[]} inviteIds - The IDs of invites to restore.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the invites. You can pass to its `returnLinkableKeys`
* property any of the invite's relation attribute names.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored.
*
* If there are no related records restored, the promise resolves to `void`.
*
* @example
* await userModuleService.restoreInvites([
* "invite_123", "invite_321"
* ])
*/
restoreInvites<TReturnableLinkableKeys extends string = string>(
inviteIds: string[],
config?: RestoreReturn<TReturnableLinkableKeys>,

2
www/utils/packages/docblock-generator/src/utils/filter-files.ts
View File

@@ -4,7 +4,7 @@ export default function (files: string[]): string[] {
return files.filter((file) =>
minimatch(
file,
"**/packages/@(medusa|types|medusa-js|medusa-react)/src/**/*.@(ts|tsx|js|jsx)",
"**/packages/@(medusa|core/types|medusa-js|medusa-react)/src/**/*.@(ts|tsx|js|jsx)",
{
matchBase: true,
}