# @keystone-alpha/fields-auto-increment

> KeystoneJS AutoIncrement Field Type

Latest version **2.0.5** (published 2019-10-23) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @keystone-alpha/fields-auto-increment
pnpm add @keystone-alpha/fields-auto-increment
yarn add @keystone-alpha/fields-auto-increment
bun add @keystone-alpha/fields-auto-increment
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.0.5 |
| Published | 2019-10-23 |
| First published | 2019-07-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=8.4.0 |
| Dependencies | 3 |
| Unpacked size | 23.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 67 |
| Author | The KeystoneJS Development Team |
| Maintainers | dominikwilkowski, jedwatson, jesstelford, mitchellhamilton, molomby, timl |

## Links

- npm: https://www.npmjs.com/package/@keystone-alpha/fields-auto-increment
- Repository: https://github.com/keystonejs/keystone-5
- Homepage: https://github.com/keystonejs/keystone-5#readme
- Issues: https://github.com/keystonejs/keystone-5/issues
- npm.io page: https://npm.io/package/@keystone-alpha/fields-auto-increment

## Dependencies (3)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.4.3
- [@keystone-alpha/fields](https://npm.io/package/@keystone-alpha/fields.md) ^15.0.0
- [@keystone-alpha/adapter-knex](https://npm.io/package/@keystone-alpha/adapter-knex.md) ^6.0.2

## Recent versions

- 2.0.5 (latest) — 2019-10-23
- 2.0.4 — 2019-10-15
- 2.0.3 — 2019-10-09
- 2.0.2 — 2019-10-02
- 2.0.1 — 2019-09-17
- 2.0.0 — 2019-09-12
- 1.0.1 — 2019-08-13
- 1.0.0 — 2019-07-19

## README

<!--[meta]
section: api
subSection: field-types
title: AutoIncrement
[meta]-->

# AutoIncrement

An automatically incrementing integer with support for the Knex adapter.
It's important to note, this type..

- Has [important limitations](#limitations) due to varying support from the underlying DB platform
- Has [non-standard defaults](#non-standard-defaults) for much of it's configuration

**Currently, outside its use as a primary key, this field type will only work on PostgreSQL.**

## Limitations

The majority of DB platforms allow only a single automatically incrementing column per table.
At time of writing (2019-07-11) this is true of
[SQLite](https://www.sqlite.org/autoinc.html),
[MySQL](https://dev.mysql.com/doc/refman/8.0/en/example-auto-increment.html),
[SQL Server](https://docs.microsoft.com/en-us/sql/t-sql/statements/create-table-transact-sql-identity-property),
[Oracle](https://docs.oracle.com/database/121/SQLRF/statements_7002.htm#SQLRF55661), and
[MariaDB](https://mariadb.com/kb/en/library/auto_increment/).
Further, it is often assumed these columns are the tables primary key.
On several platforms (eg. SQLite) auto increment functionality is _only_ available for primary keys.

Of the DB platforms supported by Knex, only
[PostgreSQL](https://www.postgresql.org/docs/9.1/datatype-numeric.html#DATATYPE-SERIAL) and
[Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html#identity-clause)
supports _multiple_ auto incrementing columns.

## Non-Standard Defaults

The configuration for `AutoIncrement` fields has different default values than most field types.
Specifically:

- `isUnique` defaults to `true` --
  As unique values are generated by the DB it's assumed this uniqueness should be enforced with a unique constraint.
- `isNotNullable` defaults to `true` --
  Likewise, it's assumed values will never be updated or explicitly set to null.
  The column is set to be not nullable to enforce this.
- Read only --
  It's assumed `AutoIncrement` are not intended to be writable.
  Some DB platform will error if you attempt to update columns created by this type.
  Further, if the column has a unique constraint (as is the default; see `isUnique` in config above)
  inserting arbitrary values may cause errors when later records are created.
  As such, fields using this type default to being read-only.
  This is implemented by defaulting the `create`, `update` and `delete` field-level access control config to `false`.

## Usage

```js
const { Keystone } = require('@keystone-alpha/keystone');
const { AutoIncrement } = require('@keystone-alpha/fields-auto-increment');

const keystone = new Keystone(/* ... */);

keystone.createList('Order', {
  fields: {
    name: { type: Text },
    orderNumber: { type: AutoIncrement, gqlType: 'Int' },
    // ...
  },
});
```

### Config

| Option       | Type      | Default       | Description                                                                                 |
| :----------- | :-------- | :------------ | :------------------------------------------------------------------------------------------ |
| `isRequired` | `Boolean` | `false`       | Does this field require a value?                                                            |
| `isUnique`   | `Boolean` | `true`        | Adds a unique index that allows only unique values to be stored                             |
| `gqlType`    | `String`  | `Int` or `ID` | The GraphQL to be used by this field. Defaults to `ID` for primary keys or `Int` otherwise. |

## Admin UI

`AutoIncrement` fields reuse the interface implementation from the native `Integer` field.

## GraphQL

`AutoIncrement` fields can use the `Int` or `ID` GraphQL types.
This can be specified using the `gqlType` config option if needed.
The default is `ID` for primary key fields and `Int` otherwise.

### Input Fields

`AutoIncrement` fields are read-only by default.
As such, input fields and types may not be added to the GraphQL schema.
See the [non-standard defaults section](#non-standard-defaults) for details.

| Field name | Type          | Description               |
| :--------- | :------------ | :------------------------ |
| `${path}`  | `Int` or `ID` | The integer value to save |

### Output Fields

| Field name | Type          | Description              |
| :--------- | :------------ | :----------------------- |
| `${path}`  | `Int` or `ID` | The integer value stored |

### Filters

| Field name       | Type              | Description                                 |
| :--------------- | :---------------- | :------------------------------------------ |
| `${path}`        | `Int` or `ID`     | Exact match to the value provided           |
| `${path}_not`    | `Int` or `ID`     | Not an exact match to the value provided    |
| `${path}_lt`     | `Int` or `ID`     | Less than the value provided                |
| `${path}_lte`    | `Int` or `ID`     | Less than or equal to the value provided    |
| `${path}_gt`     | `Int` or `ID`     | Greater than the value provided             |
| `${path}_gte`    | `Int` or `ID`     | Greater or equal to than the value provided |
| `${path}_in`     | `[Int]` or `[ID]` | In the array of integers provided           |
| `${path}_not_in` | `[Int]` or `[ID]` | Not in the array of integers provided       |

## Storage

### Knex Adapter

The `AutoIncrement` field type uses [`increments()`](https://knexjs.org/#Schema-increments) by default.
The underlying implementation varies in significant ways depending on the DB platform used (see [limitations](#limitations)).

One implication of `increments()` is that Knex will
[always make it the primary key](https://github.com/tgriesser/knex/issues/385) of the table.
To work around this, if this type is not being used as the lists primary key,
we replace the generic `increments()` call with an explicitly build `serial` column.
This work around only supports PostgreSQL; on other DB platforms, this type can only be used for the `id` field.
See the [Limitations section](#limitations) more about auto inc and their usage as primary keys.

### Mongoose Adapter

Not supported.

---
_Source: https://npm.io/package/@keystone-alpha/fields-auto-increment · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._