> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# Method name: beforeInsert(item: object, context: HookContext)

# Method package: wixDataHooks

# Method menu location: wixDataHooks --> beforeInsert

# Method Link: https://dev.wix.com/docs/velo/events-service-plugins/data/hooks/wix-data-hooks/before-insert.md

# Method Description:

A hook that is triggered before an `insert()` operation.

The `beforeInsert()` hook runs when:

 + The [`insert()`](wix-data.html#insert) function is called.
 + An action is performed on a dataset that inserts a new item into the collection.
 + An item is inserted using the CMS.
 + An item is imported into the Sandbox or Live collection.


 The hook also runs when an action is performed on a dataset that inserts a
 new item into the collection that the dataset is connected to.

 Return an object or a Promise that resolves to an object from the `beforeInsert()`
 function. The returned object will be inserted into the collection instead of
 the original item passed to the [`insert()`](wix-data.html#insert) function.

 If the returned value is of the wrong type, the value is ignored.

 A rejected Promise blocks the call to [`insert()`](wix-data.html#insert)
 and also calls the [`onFailure()`](#onFailure) hook if it has been registered.

 Because the `beforeInsert()` hook is called before [`insert()`](wix-data.html#insert)
 is executed, it can affect the item that is inserted into the collection
 or block the [`insert()`](wix-data.html#insert).



# Method Code Examples:

*** Note: do not assume any prop names or enum values other than the ones in the example.

## A beforeInsert hook

```javascript
// In data.js

export function myCollection_beforeInsert(item, context) {
  let hookContext = context;  // see below

  // some change to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */
```

## Change the item to insert using a beforeInsert hook

```javascript
// In data.js

export function myCollection_beforeInsert(item, context) {
  let hookContext = context;  // see below

  // some change to the received item
  item.title = toUpperFirst(item.title);
  item.first_name = toUpperFirst(item.first_name);
  item.last_name = toUpperFirst(item.last_name);

  return item;
}

function toUpperFirst(s) {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */
```

## Validate an email address field using a beforeInsert hook

```javascript
// In data.js

export function myCollection_beforeInsert(item, context) {
  let hookContext = context;  // see below

  //validate the email field and reject in case of failure
  const emailRegex = /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/;

  if (emailRegex.test(item.email)) {
      return item;
  } else {
      return Promise.reject('Invalid email address.');
  }
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */
```

---