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

docs-util: update knowledge base of docblock-generator (#8323)

Browse Source 
* docs: update knowledge base for functions and filters

* fix build error
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-07-29 12:34:25 +03:00
1 parent a171057fd7
commit f9d86683e5
1 file changed
+271 -109
Download Patch File Download Diff File Expand all files Collapse all files
www/utils/packages/docblock-generator/src/classes/helpers/knowledge-base-factory.ts
+271 -109
View File
@@ -1,7 +1,6 @@
import ts from "typescript" import ts from "typescript"
import { import {
API_ROUTE_PARAM_REGEX, API_ROUTE_PARAM_REGEX,
DOCBLOCK_DOUBLE_LINES,
DOCBLOCK_NEW_LINE, DOCBLOCK_NEW_LINE,
SUMMARY_PLACEHOLDER, SUMMARY_PLACEHOLDER,
} from "../../constants.js" } from "../../constants.js"
@@ -15,6 +14,8 @@ import {
} from "utils" } from "utils"
import { normalizeName } from "../../utils/str-formatting.js" import { normalizeName } from "../../utils/str-formatting.js"
const singular = pluralize.singular
type TemplateOptions = { type TemplateOptions = {
pluralIndicatorStr?: string pluralIndicatorStr?: string
parentName?: string parentName?: string
@@ -213,184 +214,306 @@ class KnowledgeBaseFactory {
return `The main service interface for the ${normalizedStr} Module.` return `The main service interface for the ${normalizedStr} Module.`
}, },
}, },
{
exact: "$eq",
template: () => {
return `Find records whose property exactly matches this value.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$ne",
template: () => {
return `Find records whose property doesn't matches this value.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$in",
template: () => {
return `Find records whose property is within the specified values.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$nin",
template: () => {
return `Find records whose property isn't within the specified values.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$like",
template: () => {
return `Find records whose property satisfies this like filter. For example, \`My%\`.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$ilike",
template: () => {
return `Find records whose property satisfies this [ilike filter](https://www.postgresql.org/docs/current/functions-matching.html). For example, \`My%\`.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$re",
template: () => {
return `Find records whose property matches this regular expression pattern.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$contains",
template: () => {
return `Find records whose property is an array that has one or more items.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$gt",
template: () => {
return `Find records whose property's value is greater than the specified number or date.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$gte",
template: () => {
return `Find records whose property's value is greater than or equal to the specified number or date.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$lt",
template: () => {
return `Find records whose property's value is less than the specified number or date.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
{
exact: "$lte",
template: () => {
return `Find records whose property's value is less than or equal to the specified number or date.`
},
kind: [ts.SyntaxKind.PropertySignature],
},
] ]
private functionSummaryKnowledgeBase: KnowledgeBase[] = [ private functionSummaryKnowledgeBase: KnowledgeBase[] = [
{ {
startsWith: "listAndCount", startsWith: "listAndCount",
template: (_str, options) => { template: (str) => {
return this.replaceTypePlaceholder( const { pluralName } = this.getPluralConfigForFunction({
`retrieves a paginated list of ${this.TYPE_PLACEHOLDER}s along with the total count of available ${this.TYPE_PLACEHOLDER}s satisfying the provided filters.`, str,
options replacement: "listAndCount",
) })
return `retrieves a paginated list of ${pluralName} along with the total count of available ${pluralName} satisfying the provided filters.`
}, },
}, },
{ {
startsWith: "list", startsWith: "list",
template: (_str, options) => { template: (str) => {
return this.replaceTypePlaceholder( const { pluralName } = this.getPluralConfigForFunction({
`retrieves a paginated list of ${this.TYPE_PLACEHOLDER}s based on optional filters and configuration.`, str,
options replacement: "list",
) })
return `retrieves a paginated list of ${pluralName} based on optional filters and configuration.`
}, },
}, },
{ {
startsWith: "retrieve", startsWith: "retrieve",
template: (_str, options) => { template: (str) => {
return this.replaceTypePlaceholder( const { singularName } = this.getPluralConfigForFunction({
`retrieves a ${this.TYPE_PLACEHOLDER} by its ID.`, str,
options replacement: "retrieve",
) })
return `retrieves a ${singularName} by its ID.`
}, },
}, },
{ {
startsWith: "create", startsWith: "create",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { article, isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`creates${!isPlural ? " a" : ""} ${this.TYPE_PLACEHOLDER}${ str,
isPlural ? "s" : "" replacement: "create",
}.`, options,
options })
) return `creates${article} ${isPlural ? pluralName : singularName}.`
}, },
}, },
{ {
startsWith: "delete", startsWith: "delete",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { article, isPlural, pronoun, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`deletes${!isPlural ? " a" : ""} ${this.TYPE_PLACEHOLDER} by ${ str,
isPlural ? "their" : "its" replacement: "delete",
} ID${isPlural ? "s" : ""}.`, options,
options })
) return `deletes${article} ${
isPlural ? pluralName : singularName
} by ${pronoun} ID${isPlural ? "s" : ""}.`
}, },
}, },
{ {
startsWith: "update", startsWith: "update",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { article, isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`updates${!isPlural ? " an" : ""} existing ${this.TYPE_PLACEHOLDER}${ str,
isPlural ? "s" : "" replacement: "update",
}.`, options,
options })
) return `updates${article} existing ${
isPlural ? pluralName : singularName
}.`
}, },
}, },
{ {
startsWith: "softDelete", startsWith: "softDelete",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { article, pronoun, isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`soft deletes${!isPlural ? " a" : ""} ${this.TYPE_PLACEHOLDER}${ str,
isPlural ? "s" : "" replacement: "softDelete",
} by ${isPlural ? "their" : "its"} IDs.`, options,
options })
) return `soft deletes${article} ${
isPlural ? pluralName : singularName
} by ${pronoun} IDs.`
}, },
}, },
{ {
startsWith: "restore", startsWith: "restore",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { article, pronoun, isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`restores${!isPlural ? " a" : ""} soft deleted ${ str,
this.TYPE_PLACEHOLDER replacement: "restore",
}${isPlural ? "s" : ""} by ${isPlural ? "their" : "its"} IDs.`, options,
options })
) return `restores${article} soft deleted ${
isPlural ? pluralName : singularName
} by ${pronoun} ID${isPlural ? "s" : ""}.`
}, },
}, },
{ {
startsWith: "upsert", startsWith: "upsert",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { article, isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`updates or creates${!isPlural ? " a" : ""} ${this.TYPE_PLACEHOLDER}${ str,
isPlural ? "s" : "" replacement: "upsert",
} if ${isPlural ? "they don't" : "it doesn't"} exist.`, options,
options })
) return `updates or creates${article} ${
isPlural ? pluralName : singularName
} if ${isPlural ? "they don't" : "it doesn't"} exist.`
}, },
}, },
] ]
private functionReturnKnowledgeBase: KnowledgeBase[] = [ private functionReturnKnowledgeBase: KnowledgeBase[] = [
{ {
startsWith: "listAndCount", startsWith: "listAndCount",
template: (_str, options) => { template: (str, options) => {
return this.replaceTypePlaceholder( const { isPlural, singularName, pluralName } =
`The list of ${this.TYPE_PLACEHOLDER}s along with their total count.`, this.getPluralConfigForFunction({
options str,
) replacement: "upsert",
options,
})
return `The list of ${
isPlural ? pluralName : singularName
} along with their total count.`
}, },
}, },
{ {
startsWith: "list", startsWith: "list",
template: (_str, options) => { template: (str, options) => {
return this.replaceTypePlaceholder( const { isPlural, singularName, pluralName } =
`The list of ${this.TYPE_PLACEHOLDER}s.`, this.getPluralConfigForFunction({
options str,
) replacement: "upsert",
options,
})
return `The list of ${isPlural ? pluralName : singularName}.`
}, },
}, },
{ {
startsWith: "retrieve", startsWith: "retrieve",
template: (_str, options) => { template: (str, options) => {
return this.replaceTypePlaceholder( const { isPlural, singularName, pluralName } =
`The retrieved ${this.TYPE_PLACEHOLDER}.`, this.getPluralConfigForFunction({
options str,
) replacement: "upsert",
options,
})
return `The retrieved ${isPlural ? pluralName : singularName}.`
}, },
}, },
{ {
startsWith: "create", startsWith: "create",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`The created ${this.TYPE_PLACEHOLDER}${isPlural ? "s" : ""}.`, str,
options replacement: "upsert",
) options,
})
return `The created ${isPlural ? pluralName : singularName}.`
}, },
}, },
{ {
startsWith: "update", startsWith: "update",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`The updated ${this.TYPE_PLACEHOLDER}${isPlural ? "s" : ""}.`, str,
options replacement: "upsert",
) options,
})
return `The updated ${isPlural ? pluralName : singularName}.`
}, },
}, },
{ {
startsWith: "upsert", startsWith: "upsert",
template: (_str, options) => { template: (str, options) => {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr) const { isPlural, singularName, pluralName } =
return this.replaceTypePlaceholder( this.getPluralConfigForFunction({
`The created or updated ${this.TYPE_PLACEHOLDER}${ str,
isPlural ? "s" : "" replacement: "upsert",
}.`, options,
options })
) return `The created or updated ${isPlural ? pluralName : singularName}.`
}, },
}, },
{ {
startsWith: "softDelete", startsWith: "softDelete",
template: (_str, options) => { template: (str, options) => {
return this.replaceTypePlaceholder( const { isPlural, singularName, pluralName } =
`An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated {related entity name}. ${DOCBLOCK_NEW_LINE}The object's keys are the ID attribute names of the ${this.TYPE_PLACEHOLDER} entity's relations, such as \`{relation ID field name}\`, and its value is an array of strings, each being the ID of a record associated ${DOCBLOCK_NEW_LINE}with the ${this.TYPE_PLACEHOLDER} through this relation, such as the IDs of associated {related entity name}.${DOCBLOCK_DOUBLE_LINES}If there are no related records, the promise resolves to \`void\`.`, this.getPluralConfigForFunction({
options str,
) replacement: "softDelete",
options,
})
return `An object whose keys are of the format \`{camel_case_data_model}_id\` and values are arrays of IDs of soft-deleted ${
isPlural ? pluralName : singularName
}`
}, },
}, },
{ {
startsWith: "restore", startsWith: "restore",
template: (_str, options) => { template: (str, options) => {
return this.replaceTypePlaceholder( const { isPlural, singularName, pluralName } =
`An object that includes the IDs of related records that were restored, such as the ID of associated {relation name}. ${DOCBLOCK_NEW_LINE}The object's keys are the ID attribute names of the ${this.TYPE_PLACEHOLDER} entity's relations, such as \`{relation ID field name}\`, ${DOCBLOCK_NEW_LINE}and its value is an array of strings, each being the ID of the record associated with the ${this.TYPE_PLACEHOLDER} through this relation, ${DOCBLOCK_NEW_LINE}such as the IDs of associated {relation name}.${DOCBLOCK_DOUBLE_LINES}If there are no related records restored, the promise resolves to \`void\`.`, this.getPluralConfigForFunction({
options str,
) replacement: "restore",
options,
})
return `An object whose keys are of the format \`{camel_case_data_model}_id\` and values are arrays of IDs of restored ${
isPlural ? pluralName : singularName
}`
}, },
}, },
] ]
@@ -483,6 +606,45 @@ class KnowledgeBaseFactory {
return str.replaceAll(this.TYPE_PLACEHOLDER, typeName) return str.replaceAll(this.TYPE_PLACEHOLDER, typeName)
} }
/**
* This method retrieves plural configuration for Medusa service's functions.
*
* @param param0 - The function's input.
* @returns The plural configurations.
*/
private getPluralConfigForFunction({
str,
replacement,
options,
}: {
str: string
replacement: string
options?: TemplateOptions
}): {
isPlural: boolean
typeName: string
singularName: string
pluralName: string
article: string
pronoun: string
} {
const isPlural = this.isTypePlural(options?.pluralIndicatorStr)
const typeName = camelToWords(str.replace(replacement, ""))
const singularName = singular(typeName)
const pluralName = pluralize(typeName)
const article = isPlural ? "" : " a"
const pronoun = isPlural ? "their" : "its"
return {
isPlural,
typeName,
singularName,
pluralName,
article,
pronoun,
}
}
/** /**
* Checks whether a type should be handled as a plural. Typically used with {@link TemplateOptions.pluralIndicatorStr}. * Checks whether a type should be handled as a plural. Typically used with {@link TemplateOptions.pluralIndicatorStr}.
* *