@wix/patterns-fields-utils 1.0.0

package/@wix/wix-data-schema-types/src/field.ts

@@ -0,0 +1,355 @@
+import { FieldPlugins } from './fieldPlugins'
+
+/**
+ * @interface FieldSpec
+ * @member displayName {string} - Defines UI-friendly name of a field. This name is used in Content Manager
+ * header and when binding to the field in Data Binding.
+ * @member type {FieldType} - Defines field data type.
+ * @member systemField {boolean} - Defines field is system or user created field.
+ * @member queryOperators {Array<AllowedFilterOperator>} - Denotes which filter operators can be used on field. This limits
+ * the filters that are available in Content Manager and Dataset. Wix Data, however, will not validate filters
+ * passed by user from code. Undefined implies default type operators are supported, empty array - no filters
+ * are supported on the field.
+ * @member sortable {boolean} - Defines the field is sortable or not. Similarly to queryOperators, impacts
+ * Content Manager and Data Binding.
+ * @member isDeleted {boolean} - Deleted fields are hidden from data results, also excluded from sorts
+ * and filters.
+ * @member index {number} - Defines field order in cases where fields are ordered, e.g., Content Manager.
+ * @member pii {boolean} - Indicates that field contains PII data and should be encrypted.
+ * @member calculator {Calculator} - Defines how virtual data should be generated.
+ * @member linkedRouterPage {string} - Defines reference to router pattern in the site document
+ * @member minValue {number} - Min possible value for the field.
+ * @member maxValue {number} - Max possible value for the field.
+ * @member minStrLength {number} - Min length for the string field.
+ * @member maxStrLength {number} - Max length for the string field.
+ * @member minArraySize {number} - Min size for the repeated field.
+ * @member maxArraySize {number} - Max size for the repeated field.
+ * @member readOnly {boolean} - Indicates that the field cannot be set by the client. E.g. Id field assigned by the server.
+ * @member immutable {boolean} - Indicates that the field can be set by the client, but can never be changed or updated.
+ * @member required {boolean} - Indicates that the field is required.
+ */
+export type FieldSpec = {
+  displayName: string
+  type: FieldType
+  systemField: boolean
+  queryOperators?: AllowedFilterOperator[]
+  sortable?: boolean
+  isDeleted?: boolean
+  index?: number
+  pii?: boolean
+  calculator?: Calculator
+  linkedRouterPage?: string
+  description?: string
+  minValue?: number
+  maxValue?: number
+  minStrLength?: number
+  maxStrLength?: number
+  minArraySize?: number
+  maxArraySize?: number
+  readOnly?: boolean
+  immutable?: boolean
+  required?: boolean
+  plugin?: string
+  plugins?: FieldPlugins
+  pageLinkType?: PageLinkType
+  condition?: Condition
+} & ValidFieldTypes
+
+export type NestedFieldSpec = {
+  type: FieldType
+  displayName?: string
+  queryOperators?: AllowedFilterOperator[]
+  sortable?: boolean
+} & ValidNestedFieldTypes
+
+export type ValidFieldTypes = ReferenceField | MultiReferenceField | ValidNestedFieldTypes | SlugField
+
+export type ValidNestedFieldTypes = TextField | NumberField | DateTimeField | DateField | ImageField | BoolField | DocumentField | UrlField | EmailField |
+  RichTextField | VideoField | PageLinkField | MediaGalleryField | AddressField | AnyField | ArrayStringField | ArrayDocumentField |
+  AudioField | TimeField | LanguageField | RichContentField | ColorField | ArrayField | ObjectField
+
+export interface Calculator {
+  config: {
+    pattern: string,
+    lowercase: boolean
+  }
+}
+
+export enum FieldType {
+  /**
+   * JSON Number (Ex. 2 or 26.7)
+   */
+  number = 'number',
+
+  /**
+   * JSON String
+   */
+  text = 'text',
+
+  /**
+   * Wix Media or HTTP(S) url to an image,
+   * image://...
+   */
+  image = 'image',
+
+  /**
+   * JSON Boolean (true, false)
+   */
+  boolean = 'boolean',
+
+  /**
+   * Wix Media link to a document, in form wix:media://...
+   */
+  document = 'document',
+
+  /**
+   * HTTP(S) URL as a JSON String
+   */
+  url = 'url',
+
+  /**
+   * Email address as a JSON String
+   */
+  email = 'email',
+
+  /**
+   * HTML String with tags allowed in Wix RichText.
+   */
+  richText = 'richtext',
+
+  /**
+   * Date type represented as an object with $date attribute
+   * holding ISO 8601 string with UTC date.
+   *
+   * Example: { $date: '2018-04-01T00:00:00Z' }
+   *
+   * This will get transformed to JavaScript Date on the client side.
+   * It is similar to 'dateTime', except for the time part:
+   * time always is 00:00:00Z
+   */
+   date = 'date',
+
+  /**
+   * Date time type represented as an object with $date attribute
+   * holding ISO 8601 string with UTC date.
+   *
+   * Example: { $date: '2018-04-01T00:00:00Z' }
+   *
+   * This will get transformed to JavaScript Date on the client side.
+   */
+  dateTime = 'datetime',
+
+  /**
+   * Wix Media link to video
+   */
+  video = 'video',
+
+  /**
+   * String ID to referenced item.
+   *
+   * If specified in a collection together with referencedCollectionName,
+   * Wix Data will handle the includes by making additional request to
+   * included collection using hasSome filter and passing down ids of the
+   * items to be included.
+   */
+  reference = 'reference',
+
+  /**
+   * Multi-reference fields are not yet directly supported in DB Drivers.
+   * Consult Wix Data team before trying to use it.
+   */
+  multiReference = 'multi-reference',
+
+  /**
+   * Relative URL to a page in a site.
+   */
+  pageLink = 'pagelink',
+
+  /**
+   * JSON Object as plain JSON.
+   */
+  object = 'object',
+
+  /**
+   * Gallery type for binding to Pro Gallery components.
+   */
+  mediaGallery = 'media-gallery',
+
+  /**
+   * Address type.
+   * See https://docs.google.com/document/d/1pwZKxnBBxR1mBnJGiS6M6qSdjKd1YDJ2OAM4nHJjFS8/edit#heading=h.5ndfgx3b0knm
+   *
+   * Items should at very least contain 'formatted' property.
+   */
+  address = 'address',
+
+  /**
+   * Array of strings type.
+   */
+  stringArray = 'array<string>',
+
+  /**
+   * JSON Color Hex String
+   */
+  color = 'color',
+
+  /**
+   * Wix Media link to audio
+   */
+  audio = 'audio',
+
+  /**
+   * JSON String holding time in a following format: '00:00:00'
+   */
+  time = 'time',
+
+  /**
+   * Array
+   */
+  array = 'array',
+
+  /**
+   * RichContent type for binding to RichContentEditor/RichContentViewer components
+   * based on Ricos https://github.com/wix-incubator/rich-content
+   */
+  richContent = 'rich-content',
+
+  /**
+   * Text string holding language name in which row content is translated. Complies with BCP47 standard: https://tools.ietf.org/html/bcp47#appendix-A
+   */
+  language = 'language',
+
+  /**
+   * Array of documents, see {@link FieldType.document}
+   */
+  documentArray = 'array<document>',
+
+  /**
+   * Any JSON data type
+   */
+  any = 'any',
+
+  /**
+   * Slug type used for dynamic page URLs.
+   */
+  slug = 'slug',
+
+  legacyBook = 'bookType',
+
+  legacyExternalUrl = 'externalUrl',
+
+  legacyBrokenRef = 'broken-reference',
+
+  legacyExternalVideo = 'externalVideo',
+
+  legacyImage = 'Image'
+}
+
+export type TextField = { type: FieldType.text }
+export type NumberField = { type: FieldType.number }
+export type DateTimeField = { type: FieldType.dateTime }
+export type DateField = { type: FieldType.date }
+export type ImageField = { type: FieldType.image }
+export type BoolField = { type: FieldType.boolean }
+export type DocumentField = { type: FieldType.document }
+export type UrlField = { type: FieldType.url }
+export type EmailField = { type: FieldType.email }
+export type RichTextField = { type: FieldType.richText }
+export type VideoField = { type: FieldType.video }
+export type PageLinkField = { type: FieldType.pageLink }
+export type MediaGalleryField = { type: FieldType.mediaGallery }
+export type AddressField = { type: FieldType.address }
+export type AnyField = { type: FieldType.any }
+export type ArrayStringField = { type: FieldType.stringArray }
+export type ArrayDocumentField = { type: FieldType.documentArray }
+export type AudioField = { type: FieldType.audio }
+export type TimeField = { type: FieldType.time }
+export type LanguageField = { type: FieldType.language }
+export type RichContentField = { type: FieldType.richContent }
+export type ColorField = { type: FieldType.color }
+
+/**
+ * @member referencedCollection {string} - Denotes referenced collection name.
+ */
+export type ReferenceField = {
+  type: FieldType.reference
+  referencedCollection: string
+}
+
+/**
+ * @member referencedCollection {string} - Denotes referenced collection name.
+ * @member referencingFieldKey {string} - Denotes the field key to represent current collection items
+ * in referenced collection.
+ * @member referencingDisplayName {string} - Defines UI-friendly name for field that represents current
+ * collection items in referenced collection. This name is used in Content Manager header and when
+ * binding to the field in Data Binding.
+ */
+export type MultiReferenceField = {
+  type: FieldType.multiReference
+  referencedCollection: string
+  referencingFieldKey: string
+  referencingDisplayName?: string
+}
+
+/**
+ * @member elementType {NestedFieldSpec} - Denotes type of elements in array.
+ */
+export type ArrayField = {
+  type: FieldType.array,
+  elementType?: ValidNestedFieldTypes
+}
+
+/**
+ * @member elementType { [fieldName: string]: NestedFieldSpec } - Denotes structure of the the object.
+ */
+export type ObjectField = {
+  type: FieldType.object,
+  fields?: { [fieldName: string]: NestedFieldSpec }
+}
+
+/**
+ * @member pattern {string} - Denotes pattern for generating slug values.
+ */
+export type SlugField = {
+  type: FieldType.slug,
+  pattern: string
+}
+
+export enum AllowedFilterOperator {
+  eq = 'eq',
+  ne = 'ne',
+  lt = 'lt',
+  lte = 'lte',
+  gt = 'gt',
+  gte = 'gte',
+  hasSome = 'hasSome',
+  hasAll = 'hasAll',
+  contains = 'contains',
+  startsWith = 'startsWith',
+  endsWith = 'endsWith',
+  urlized = 'urlized',
+  exists = 'exists'
+}
+
+export enum PageLinkType {
+  COLLECTION_DEFINED = 'COLLECTION_DEFINED',
+  ROUTER_DEFINED = 'ROUTER_DEFINED'
+}
+
+export enum FieldPermission {
+  /** No special permissions required to read the field (visitors) */
+  ANYONE,
+
+  /**
+   * Special permissions required to read the field (members, contributors, etc.)
+   */
+  RESTRICTED,
+}
+
+export type Condition = {
+  /** Conditional (requested) field enum value */
+  groupName?: string
+
+  /** Who can read the field? */
+  permission: FieldPermission
+}

package/@wix/wix-data-schema-types/src/fieldPlugins.ts

@@ -0,0 +1,28 @@
+
+export const CMS_FIELD_PLUGIN_ID = 'cms'
+export interface CmsFieldPlugin {
+  // marks CMS-internal field, that should not be displayed anywhere
+  internal: boolean
+}
+
+export const CATEGORY_FIELD_PLUGIN_ID = 'categoryField'
+export interface CategoryFieldPlugin {
+  isPrimary: boolean
+}
+
+export const PRIMARY_CATEGORY_FIELD_PLUGIN_ID = 'primaryCategoryField'
+export interface PrimaryCategoryFieldPlugin {}
+
+export const CATEGORY_CONSUMER_FIELD_PLUGIN_ID = 'categoryConsumer'
+export interface CategoryConsumerFieldPlugin {}
+
+export interface KnownFieldPlugins {
+  [CMS_FIELD_PLUGIN_ID]?: CmsFieldPlugin
+  [CATEGORY_FIELD_PLUGIN_ID]?: CategoryFieldPlugin
+  [PRIMARY_CATEGORY_FIELD_PLUGIN_ID]?: PrimaryCategoryFieldPlugin
+  [CATEGORY_CONSUMER_FIELD_PLUGIN_ID]?: CategoryConsumerFieldPlugin
+}
+
+export type FieldPlugins = KnownFieldPlugins & Record<string, object>
+export type FieldPluginId = keyof KnownFieldPlugins
+export type FieldPlugin = Required<KnownFieldPlugins>[FieldPluginId]

package/@wix/wix-data-schema-types/src/filter.ts

@@ -0,0 +1,280 @@
+/**
+ * @type Filter
+ * @description Filter is a single condition filter or a combination of conditions through And or Or filters.
+ */
+export type Filter = And | Or | Not | Eq | Ne | Lt | Lte | Gt | Gte |
+    HasSome | HasAll | Contains | StartsWith | EndsWith | Urlized
+
+/**
+ * @enum Operator
+ * @description Provides values for filter operator.
+ * @member and to combine multiple filters with an and.
+ * @member or to combine multiple filters with an or.
+ * @member not to add filter witch has to be not matched.
+ * @member eq to add `equality` condition to filter.
+ * @member ne to add `not equal` condition to filter.
+ * @member lt to add `les than` condition to filter.
+ * @member lte to add `tess than or equal` condition to filter.
+ * @member gt to add `greater than` condition to filter.
+ * @member gte to add `greater than or equal` condition to filter.
+ * @member hasSome to add `has some values of provided` condition to filter.
+ * @member hasAll to add `has all values of provided` condition to filter.
+ * @member contains to add `field value contains provided value` condition to filter.
+ * @member startsWith to add `field value starts with provided value` condition to filter.
+ * @member endsWith to add `ends with provided value` condition to filter.
+ * @member urlized to add `urlized provided value` condition to filter.
+ */
+export enum Operator {
+    and = '$and',
+    or = '$or',
+    not = '$not',
+    eq = '$eq',
+    ne = '$ne',
+    lt = '$lt',
+    lte = '$lte',
+    gt = '$gt',
+    gte = '$gte',
+    hasSome = '$hasSome',
+    hasAll = '$hasAll',
+    contains = '$contains',
+    startsWith = '$startsWith',
+    endsWith = '$endsWith',
+    urlized = '$urlized'
+}
+
+/**
+ * @type Literal
+ * @description Describes types used in some of filters
+ */
+export type Literal = string | number | Date | null
+
+export interface FilterInterface {
+  kind: 'filter'
+}
+
+/**
+ * @interface And
+ * @member operator - `and` operator.
+ * @member value - `Array` of `Filter`.
+ * @description A filter with an `and` returns all the items that match all filters in `and` filter array.
+ * @example Filter where `someField` is between 6 and 12
+ * const andFilter: And = {
+ *   operator: Operator.and,
+ *   value: [
+ *      {operator: Operator.gt, fieldName: 'someField', value:6},
+ *      {operator: Operator.lt, fieldName: 'someField', value:12}
+ *   ]
+ * }
+ */
+export interface And extends FilterInterface {
+  operator: Operator.and
+  value: Filter[]
+}
+
+/**
+ * @interface Or
+ * @member operator - `or` operator
+ * @member value - `Array` of `Filter`.
+ * @description A filter with an `or` returns all the items that match at least one filter in `or` filter array.
+ * @example Filter where `someField` equals "hi" or "bye"
+ * const orFilter: Or = {
+ *   operator: Operator.or,
+ *   value: [
+ *      {operator: Operator.eq, fieldName: 'someField', value:'hi'},
+ *      {operator: Operator.eq, fieldName: 'someField', value:'bye'}
+ *   ]
+ * }
+ */
+export interface Or extends FilterInterface {
+  operator: Operator.or
+  value: Filter[]
+}
+
+/**
+ * @interface Not
+ * @member operator - `not` operator.
+ * @member value - `Filter`.
+ * @description A query with a `not` returns all the items that match the filter as defined up to the `not`
+ * operator, but don't match the filter under the `not` operator.
+ * @example Filter where `someField` not equals "hi"
+ * const notFilter: Not = {
+ *   operator: Operator.not,
+ *   value: {operator: Operator.eq, fieldName: 'someField', value: 'hi'}
+ * }
+ */
+export interface Not extends FilterInterface {
+  operator: Operator.not
+  value: Filter
+}
+
+/**
+ * @interface Eq
+ * @member operator - `eq`
+ * @member fieldName - field witch has to be equal to `value`
+ * @member value - value to match a field value. Value can be any type.
+ * @example Filter where `someField` equals "hi"
+ * const eq: Eq = {operator: Operator.eq, fieldName: 'someField', value: 'hi'}
+ */
+export interface Eq extends FilterInterface {
+  operator: Operator.eq
+  fieldName: string
+  value: any
+}
+
+/**
+ * @interface Ne
+ * @member operator - `ne` not equal
+ * @member fieldName - field witch has to be not equal to `value`
+ * @member value - value to not match a field value. Value can be any type.
+ * @example Filter where `someField` not equals "hi"
+ * const ne: Ne = {operator: Operator.ne, fieldName: 'someField', value: 'hi'}
+ */
+export interface Ne extends FilterInterface {
+  operator: Operator.ne
+  fieldName: string
+  value: any
+}
+
+/**
+ * @interface Lt
+ * @member operator - `lt` less than
+ * @member fieldName - field witch has to be less than to `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` is less than 6
+ * const lt: Lt = {operator: Operator.lt, fieldName: 'someField', value: 6}
+ */
+export interface Lt extends FilterInterface {
+  operator: Operator.lt
+  fieldName: string
+  value: Literal
+}
+
+/**
+ * @interface Lte
+ * @member operator - `lte` less than or equal
+ * @member fieldName - field witch has to be less than or equal to `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` is less than or equal to 6
+ * const lte: Lte = {operator: Operator.lte, fieldName: 'someField', value: 6}
+ */
+export interface Lte extends FilterInterface {
+  operator: Operator.lte
+  fieldName: string
+  value: Literal
+}
+
+/**
+ * @interface Gt
+ * @member operator - `gt` greater than
+ * @member fieldName - field witch has to be greater than to `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` is greater than 6
+ * const gt: Gt = {operator: Operator.gt, fieldName: 'someField', value: 6}
+ */
+export interface Gt extends FilterInterface {
+  operator: Operator.gt
+  fieldName: string
+  value: Literal
+}
+
+/**
+ * @interface Gte
+ * @member operator - `gte` greater than or equal
+ * @member fieldName - field witch has to be greater than or equal to `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` is greater than or equal to 6
+ * const gte: Gte = {operator: Operator.gte, fieldName: 'someField', value: 6}
+ */
+export interface Gte extends FilterInterface {
+  operator: Operator.gte
+  fieldName: string
+  value: Literal
+}
+
+/**
+ * @interface StartsWith
+ * @member operator - `startsWith` starts with
+ * @member fieldName - field witch has to start with `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` starts with "hel"
+ * const startsWith: StartsWith = {operator: Operator.startsWith, fieldName: 'someField', value: 'hel'}
+ */
+export interface StartsWith extends FilterInterface {
+  operator: Operator.startsWith
+  fieldName: string
+  value: string
+}
+
+/**
+ * @interface EndsWith
+ * @member operator - `endsWith` starts with
+ * @member fieldName - field witch has to end with `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` ends with "lo"
+ * const endsWith: EndsWith = {operator: Operator.endsWith, fieldName: 'someField', value: 'lo'}
+ */
+export interface EndsWith extends FilterInterface {
+  operator: Operator.endsWith
+  fieldName: string
+  value: string
+}
+
+/**
+ * @interface Urlized
+ * Tokens should be joined using `-` or ` `. I.e. value ["hello", "world"] matches "hello world" and "hello-world".
+ * @member operator - `urlized`
+ * @member ignoreCase - case sensative or not
+ * @member fieldName - field witch has to match urlized `value`
+ * @member value - array of tokens
+ * @example Filter where `someField` matches ["hello", "world"]
+ * const matches: Matches = {operator: Operator.matches,
+ * ignoreCase: true, fieldName: 'someField', value: ['hello', 'world']}
+ */
+export interface Urlized extends FilterInterface {
+  operator: Operator.urlized
+  ignoreCase: boolean
+  fieldName: string
+  value: string[]
+}
+
+/**
+ * @interface Contains
+ * @member operator - `contains`
+ * @member fieldName - field witch has to contain `value`
+ * @member value - value compare field value to.
+ * @example Filter where `someField` contains "ell"
+ * const contains: Contains = {operator: Operator.contains, fieldName: 'someField', value: 'ell'}
+ */
+export interface Contains extends FilterInterface {
+  operator: Operator.contains
+  fieldName: string
+  value: string
+}
+
+/**
+ * @interface HasSome
+ * @member operator - `hasSome`
+ * @member fieldName - field witch has to contain some of the values.
+ * @member value - values compare field values to.
+ * @example Filter where `someField` contains at least one of [1,2,3]
+ * const hasSome: HasSome = {operator: Operator.hasSome, fieldName: 'someField', value: [1,2,3]}
+ */
+export interface HasSome extends FilterInterface {
+  operator: Operator.hasSome
+  fieldName: string
+  value: Literal[]
+}
+
+/**
+ * @interface HasAll
+ * @member operator - `hasAll`
+ * @member fieldName - field witch has to contain all of the values.
+ * @member value - values compare field values to.
+ * @example Filter where `someField` contains all of [1,2,3]
+ * const hasAll: HasAll = {operator: Operator.hasAll, fieldName: 'someField', value: [1,2,3]}
+ */
+export interface HasAll extends FilterInterface {
+  operator: Operator.hasAll
+  fieldName: string
+  value: Literal[]
+}

package/@wix/wix-data-schema-types/src/index.ts

@@ -0,0 +1,9 @@
+export * from './order'
+export * from './filter'
+export * from './field'
+export * from './schema'
+export * from './pagingMode'
+export * from './plugins'
+export * from './defaultMaxPageSize'
+export * from './fieldPlugins'
+export * from './capabilities'

package/@wix/wix-data-schema-types/src/order.ts

@@ -0,0 +1,26 @@
+/**
+ * @type OrderBy
+ * @description Describes and order with a list of order specifications
+ * @example `someField` ordered ascending, `otherField` ordered descending
+ * const orderBy: OrderBy = [
+ *      {fieldName: 'someField', direction: Direction.asc},
+ *      {fieldName: 'otherField', direction: Direction.desc}
+ * ]
+ */
+export type OrderBy = OrderSpec[]
+
+/**
+ * @interface OrderSpec
+ * @description Order specification for single field.
+ * @example `someField` ordered ascending
+ * const ascOrder: OrderSpec = {fieldName: 'someField', direction: Direction.asc}
+ */
+export interface OrderSpec {
+  fieldName: string
+  direction: Direction
+}
+
+export enum Direction {
+    asc = 'asc',
+    desc = 'desc'
+}

package/@wix/wix-data-schema-types/src/pagingMode.ts

@@ -0,0 +1,4 @@
+export enum PagingMode {
+    Offset = 'OFFSET',
+    Cursor = 'CURSOR'
+}