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

chore(docs): DML API Reference (#7863)

Browse Source 
* added dml options

* added tsdocs + configurations
This commit is contained in:
Shahed Nasser
2024-07-01 10:21:56 +03:00
committed by GitHub
parent 9ded63cc62
commit 72f7500c84
20 changed files with 746 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

319
packages/core/utils/src/dml/entity-builder.ts
View File

@@ -22,7 +22,43 @@ import { ManyToMany } from "./relations/many-to-many"
*/
const IMPLICIT_PROPERTIES = ["created_at", "updated_at", "deleted_at"]
type DefineOptions = string | { name?: string; tableName: string }
export type DefineOptions = string | {
/**
* The data model's name.
*/
name?: string
/**
* The name of the data model's table in the database.
*/
tableName: string
}
export type ManyToManyOptions = RelationshipOptions &
(
| {
/**
* The name of the pivot table
* created in the database for this relationship.
*/
pivotTable?: string
/**
* @ignore
*/
pivotEntity?: never
}
| {
/**
* @ignore
*/
pivotTable?: never
/**
* A function that returns the data model
* representing the pivot table created in the
* database for this relationship.
*/
pivotEntity?: () => DmlEntity<any>
}
)
/**
* Entity builder exposes the API to create an entity and define its
@@ -44,8 +80,23 @@ export class EntityBuilder {
}
/**
* Define an entity or a model. The name should be unique across
* all the entities.
* This method defines a data model.
*
* @typeParam Schema - The type of the accepted schema in the second parameter of the method.
*
* @param {DefineOptions} nameOrConfig - Either the data model's name, or configurations to name the data model.
* The data model's name must be unique.
* @param {Schema} schema - The schema of the data model's properties.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* id: model.id(),
* name: model.text(),
* })
*
* export default MyCustom
*/
define<Schema extends DMLSchema>(
nameOrConfig: DefineOptions,
@@ -62,36 +113,102 @@ export class EntityBuilder {
}
/**
* Define an id property. Id properties are marked
* primary by default
* This method defines an automatically generated string ID property.
*
* By default, this property is considered to be the data model’s primary key.
*
* @param {ConstructorParameters<typeof IdProperty>[0]} options - The ID's options.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* id: model.id(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
id(options?: ConstructorParameters<typeof IdProperty>[0]) {
return new IdProperty(options)
}
/**
* Define a text/string based column
* This method defines a string property.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* name: model.text(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
text() {
return new TextProperty()
}
/**
* Define a boolean column
* This method defines a boolean property.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* hasAccount: model.boolean(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
boolean() {
return new BooleanProperty()
}
/**
* Define an integer column
* This method defines a number property.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* age: model.number(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
number() {
return new NumberProperty()
}
/**
* Define a numeric column. This property produces an additional
* This method defines a number property that expects large numbers, such as prices.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* price: model.bigNumber(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*
* @privateRemarks
* This property produces an additional
* column - raw_{{ property_name }}, which stores the configuration
* of bignumber (https://github.com/MikeMcl/bignumber.js)
*/
@@ -100,94 +217,198 @@ export class EntityBuilder {
}
/**
* Define an array column
* This method defines an array of strings property.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* names: model.array(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
array() {
return new ArrayProperty()
}
/**
* Define a timestampz column
* This method defines a timestamp property.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* date_of_birth: model.dateTime(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
dateTime() {
return new DateTimeProperty()
}
/**
* Define a JSON column to store data as a
* JSON string
* This method defines a property whose value is a stringified JSON object.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* metadata: model.json(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
json() {
return new JSONProperty()
}
/**
* Define an enum column where only a pre-defined set
* of values are allowed.
* This method defines a property whose value can only be one of the specified values.
*
* @typeParam Values - The type of possible values. By default, it's `string`.
*
* @param {Values[]} values - An array of possible values.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* color: model.enum(["black", "white"]),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Types
*/
enum<const Values extends unknown>(values: Values[]) {
return new EnumProperty<Values>(values)
}
/**
* Has one relationship defines a relationship between two entities
* where the owner of the relationship has exactly one instance
* of the related entity.
* This method defines a relationship between two data models,
* where the owner of the relationship has one record of the related
* data model.
*
* For example: A user "hasOne" profile
*
* You may use the "belongsTo" relationship to define the inverse
* of the "hasOne" relationship
* For example: A user "hasOne" email.
*
* Use the {@link belongsTo} method to define the inverse of this relationship in
* the other data model.
*
* @typeParam T - The type of the entity builder passed as a first parameter. By default, it's
* a function returning the related model.
*
* @param {T} entityBuilder - A function that returns the data model this model is related to.
* @param {RelationshipOptions} options - The relationship's options.
*
* @example
* import { model } from "@medusajs/utils"
*
* const User = model.define("user", {
* id: model.id(),
* email: model.hasOne(() => Email),
* })
*
* @customNamespace Relationship Methods
*/
hasOne<T>(entityBuilder: T, options?: RelationshipOptions) {
return new HasOne<T>(entityBuilder, options || {})
}
/**
* Define inverse of "hasOne" and "hasMany" relationship.
* This method defines the inverse of the {@link hasOne} or {@link hasMany} relationship.
*
* For example, a product "belongsTo" a store.
*
* @typeParam T - The type of the entity builder passed as a first parameter. By default, it's
* a function returning the related model.
*
* @param {T} entityBuilder - A function that returns the data model this model is related to.
* @param {RelationshipOptions} options - The relationship's options.
*
* @example
* const Product = model.define("product", {
* id: model.id(),
* store: model.belongsTo(() => Store, {
* mappedBy: "products",
* }),
* })
*
* @customNamespace Relationship Methods
*/
belongsTo<T>(entityBuilder: T, options?: RelationshipOptions) {
return new BelongsTo<T>(entityBuilder, options || {})
}
/**
* Has many relationship defines a relationship between two entities
* where the owner of the relationship has many instance of the
* related entity.
* This method defines a relationship between two data models,
* where the owner of the relationship has many records of the related
* data model, but the related data model only has one owner.
*
* For example:
*
* - A user "hasMany" books
* - A user "hasMany" addresses
* For example, a store "hasMany" products.
*
* @typeParam T - The type of the entity builder passed as a first parameter. By default, it's
* a function returning the related model.
*
* @param {T} entityBuilder - A function that returns the data model this model is related to.
* @param {RelationshipOptions} options - The relationship's options.
*
* @example
* import { model } from "@medusajs/utils"
*
* const Store = model.define("store", {
* id: model.id(),
* products: model.hasMany(() => Product),
* })
*
* @customNamespace Relationship Methods
*/
hasMany<T>(entityBuilder: T, options?: RelationshipOptions) {
return new HasMany<T>(entityBuilder, options || {})
}
/**
* ManyToMany relationship defines a relationship between two entities
* where the owner of the relationship has many instance of the
* related entity via a pivot table.
* This method defines a relationship between two data models,
* where both data models have many related records.
*
* For example:
*
* - A user has many teams. But a team has many users as well. So this
* relationship requires a pivot table to establish a many to many
* relationship between two entities
* For example, an order is associated with many products, and a product
* is associated with many orders.
*
* @typeParam T - The type of the entity builder passed as a first parameter. By default, it's
* a function returning the related model.
*
* @param {T} entityBuilder - A function that returns the data model this model is related to.
* @param {RelationshipOptions} options - The relationship's options.
*
* @example
* import { model } from "@medusajs/utils"
*
* const Order = model.define("order", {
* id: model.id(),
* products: model.manyToMany(() => Product),
* })
*
* const Product = model.define("product", {
* id: model.id(),
* order: model.manyToMany(() => Order),
* })
*
* @customNamespace Relationship Methods
*/
manyToMany<T>(
entityBuilder: T,
options?: RelationshipOptions &
(
| {
pivotTable?: string
pivotEntity?: never
}
| {
pivotTable?: never
pivotEntity?: () => DmlEntity<any>
}
)
options?: ManyToManyOptions
) {
return new ManyToMany<T>(entityBuilder, options || {})
}

97
packages/core/utils/src/dml/entity.ts
View File

@@ -94,10 +94,27 @@ export class DmlEntity<Schema extends DMLSchema> implements IDmlEntity<Schema> {
}
/**
* Delete actions to be performed when the entity is deleted. For example:
*
* You can configure relationship data to be deleted when the current
* entity is deleted.
* This method configures which related data models an operation, such as deletion,
* should be cascaded to.
*
* For example, if a store is deleted, its product should also be deleted.
*
* @param options - The cascades configurations. They object's keys are the names of
* the actions, such as `deleted`, and the value is an array of relations that the
* action should be cascaded to.
*
* @example
* import { model } from "@medusajs/utils"
*
* const Store = model.define("store", {
* id: model.id(),
* products: model.hasMany(() => Product),
* })
* .cascades({
* delete: ["products"],
* })
*
* @customNamespace Model Methods
*/
cascades(
options: EntityCascades<
@@ -123,7 +140,77 @@ export class DmlEntity<Schema extends DMLSchema> implements IDmlEntity<Schema> {
}
/**
* Adds indexes to be created at during model creation on the DML entity.
* This method defines indices on the data model. An index can be on multiple columns
* and have conditions.
*
* @param indexes - The index's configuration.
*
* @example
* An example of a simple index:
*
* ```ts
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* id: model.id(),
* name: model.text(),
* age: model.number()
* }).indexes([
* {
* on: ["name", "age"],
* },
* ])
*
* export default MyCustom
* ```
*
* To add a condition on the index, use the `where` option:
*
* ```ts
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* id: model.id(),
* name: model.text(),
* age: model.number()
* }).indexes([
* {
* on: ["name", "age"],
* where: {
* age: 30
* }
* },
* ])
*
* export default MyCustom
* ```
*
* The condition can also be a negation. For example:
*
* ```ts
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* id: model.id(),
* name: model.text(),
* age: model.number()
* }).indexes([
* {
* on: ["name", "age"],
* where: {
* age: {
* $ne: 30
* }
* }
* },
* ])
*
* export default MyCustom
* ```
*
* In this example, the index is created when the value of `age` doesn't equal `30`.
*
* @customNamespace Model Methods
*/
indexes(indexes: EntityIndex<Schema, string | QueryCondition<Schema>>[]) {
for (const index of indexes) {

72
packages/core/utils/src/dml/properties/base.ts
View File

@@ -30,14 +30,43 @@ export abstract class BaseProperty<T> implements PropertyType<T> {
declare $dataType: T
/**
* Apply nullable modifier on the schema
* This method indicates that a property's value can be `null`.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* price: model.bigNumber().nullable(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Configuration Methods
*/
nullable() {
return new NullableModifier<T, this>(this)
}
/**
* Define an index on the property
* This method defines an index on a property.
*
* @param {string} name - The index's name. If not provided,
* Medusa generates the name.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* id: model.id(),
* name: model.text().index(
* "IDX_MY_CUSTOM_NAME"
* ),
* })
*
* export default MyCustom
*
* @customNamespace Property Configuration Methods
*/
index(name?: string) {
this.#indexes.push({ name, type: "index" })
@@ -45,7 +74,23 @@ export abstract class BaseProperty<T> implements PropertyType<T> {
}
/**
* Define a unique index on the property
* This method indicates that a property's value must be unique in the database.
* A unique index is created on the property.
*
* @param {string} name - The unique index's name. If not provided,
* Medusa generates the name.
*
* @example
* import { model } from "@medusajs/utils"
*
* const User = model.define("user", {
* email: model.text().unique(),
* // ...
* })
*
* export default User
*
* @customNamespace Property Configuration Methods
*/
unique(name?: string) {
this.#indexes.push({ name, type: "unique" })
@@ -53,7 +98,26 @@ export abstract class BaseProperty<T> implements PropertyType<T> {
}
/**
* Define default value for the property
* This method defines the default value of a property.
*
* @param {T} value - The default value.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* color: model
* .enum(["black", "white"])
* .default("black"),
* age: model
* .number()
* .default(0),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Configuration Methods
*/
default(value: T) {
this.#defaultValue = value

16
packages/core/utils/src/dml/properties/id.ts
View File

@@ -13,7 +13,21 @@ export class IdProperty extends BaseProperty<string> {
}
}
constructor(options?: { primaryKey?: boolean; prefix?: string }) {
constructor(options?: {
/**
* Whether the ID is the data model's primary key.
*
* @defaultValue true
*/
primaryKey?: boolean
/**
* By default, Medusa shortens the data model's name and uses it as the
* prefix of all IDs. For example, `cm_123`.
*
* Use this option to specify the prefix to use instead.
*/
prefix?: string
}) {
super()
this.dataType = {
name: "id",

30
packages/core/utils/src/dml/properties/text.ts
View File

@@ -12,12 +12,42 @@ export class TextProperty extends BaseProperty<string> {
}
}
/**
* This method indicates that the property is the data model's primary key.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* code: model.text().primaryKey(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Configuration Methods
*/
primaryKey() {
this.dataType.options.primaryKey = true
return this
}
/**
* This method indicates that a text property is searchable.
*
* @example
* import { model } from "@medusajs/utils"
*
* const MyCustom = model.define("my_custom", {
* name: model.text().searchable(),
* // ...
* })
*
* export default MyCustom
*
* @customNamespace Property Configuration Methods
*/
searchable() {
this.dataType.options.searchable = true