electrodb 1.11.1 → 1.12.1

package/README.md

@@ -94,7 +94,6 @@ tasks
 
 ------------
 
-## Table of Contents
 - [ElectroDB](#electrodb)
   * [Features](#features)
   * [Table of Contents](#table-of-contents)
@@ -208,10 +207,10 @@ tasks
 - [AWS DynamoDB Client](#aws-dynamodb-client)
   * [V2 Client](#v2-client)
   * [V3 Client](#v3-client)
+- [Logging](#logging)
 - [Events](#events)
   * [Query Event](#query-event)
   * [Results Event](#results-event)
-- [Logging](#logging)
 - [Listeners](#listeners)
 - [Errors:](#errors-)
     + [No Client Defined On Model](#no-client-defined-on-model)
@@ -273,17 +272,19 @@ tasks
       - [Stores will renewals for Q4](#stores-will-renewals-for-q4)
       - [Spite-stores with release renewals this year](#spite-stores-with-release-renewals-this-year)
       - [All Latte Larrys in a particular mall building](#all-latte-larrys-in-a-particular-mall-building)
-- [Exported TypeScript Types](#exported-typescript-types)
-  * [EntityRecord Type](#entityrecord-type)
-  * [EntityItem Type](#entityitem-type)
-  * [CollectionItem Type](#collectionitem-type)
-  * [CreateEntityItem Type](#createentityitem-type)
-  * [UpdateEntityItem Type](#updateentityitem-type)
-  * [UpdateAddEntityItem Type](#updateaddentityitem-type)
-  * [UpdateSubtractEntityItem Type](#updatesubtractentityitem-type)
-  * [UpdateAppendEntityItem Type](#updateappendentityitem-type)
-  * [UpdateRemoveEntityItem Type](#updateremoveentityitem-type)
-  * [UpdateDeleteEntityItem Type](#updatedeleteentityitem-type)
+- [TypeScript](#typescript)
+  * [Custom Attributes](#custom-attributes)
+  * [Exported Types](#exported-types)
+    + [EntityRecord Type](#entityrecord-type)
+    + [EntityItem Type](#entityitem-type)
+    + [CollectionItem Type](#collectionitem-type)
+    + [CreateEntityItem Type](#createentityitem-type)
+    + [UpdateEntityItem Type](#updateentityitem-type)
+    + [UpdateAddEntityItem Type](#updateaddentityitem-type)
+    + [UpdateSubtractEntityItem Type](#updatesubtractentityitem-type)
+    + [UpdateAppendEntityItem Type](#updateappendentityitem-type)
+    + [UpdateRemoveEntityItem Type](#updateremoveentityitem-type)
+    + [UpdateDeleteEntityItem Type](#updatedeleteentityitem-type)
 - [Using ElectroDB With Existing Data](#using-electrodb-with-existing-data)
 - [Electro CLI](#electro-cli)
 - [Version 1 Migration](#version-1-migration)
@@ -776,7 +777,7 @@ attributes: {
 
 #### Set Attributes
 
-The Set attribute is arguably DynamoDB's most powerful type. ElectroDB supports String and Number Sets using the `items` property set as either `"string"` or `"number"`. 
+The Set attribute is arguably DynamoDB's most powerful type. ElectroDB supports String and Number Sets using the `items` property set as either `"string"`, `"number"`, or an array of strings or numbers. When a ReadonlyArray is provided, ElectroDB will enforce those values as a finite list of acceptable values, similar to an [Enum Attribute](#enum-attributes)
 
 In addition to having the same modeling benefits you get with other attributes, ElectroDB also simplifies the use of Sets by removing the need to use DynamoDB's special `createSet` class to work with Sets. ElectroDB Set Attributes accept Arrays, JavaScript native Sets, and objects from `createSet` as values. ElectroDB will manage the casting of values to a DynamoDB Set value prior to saving and ElectroDB will also convert Sets back to JavaScript arrays on retrieval.
 
@@ -791,6 +792,14 @@ attributes: {
   myNumberSet: {
     type: "set",
     items: "number"
+  },
+  myEnumStringSet: {
+    type: "set",
+    items: ["RED", "GREEN", "BLUE"] as const // electrodb will only accept the included values "RED", "GREEN", and/or "BLUE"
+  },
+  myEnumNumberSet: {
+    type: "set",
+    items: [1, 2, 3] as const // electrodb will only accept the included values 1, 2, and/or 3
   }
 }
 ```
@@ -1097,17 +1106,17 @@ indexes: {
 | Property       | Type                                   | Required | Description |
 | -------------- | :------------------------------------: | :------: | ----------- |
 | `pk`           | `object`                               | yes      | Configuration for the pk of that index or table
-| `pk.composite` | `string | string[]`                    | yes      | An array that represents the order in which attributes are concatenated to composite attributes the key (see [Composite Attributes](#composite-attributes) below for more on this functionality).
+| `pk.composite` | `string[]`                             | yes      | An array that represents the order in which attributes are concatenated to composite attributes the key (see [Composite Attributes](#composite-attributes) below for more on this functionality).
 | `pk.template`  | `string`                               | no       | A string that represents the template in which attributes composed to form a key (see [Composite Attribute Templates](#composite-attribute-templates) below for more on this functionality).
 | `pk.field`     | `string`                               | yes      | The name of the attribute as it exists in DynamoDB, if named differently in the schema attributes.
-| `pk.casing`    | `default` | `upper` | `lower` | `none` | no       | Choose a case for ElectroDB to convert your keys to, to avoid casing pitfalls when querying data. Default: `lower`. 
+| `pk.casing`    | `default`, `upper`, `lower`, `none`    | no       | Choose a case for ElectroDB to convert your keys to, to avoid casing pitfalls when querying data. Default: `lower`. 
 | `sk`           | `object`                               | no       | Configuration for the sk of that index or table
-| `sk.composite` | `string | string[]`                    | no       | Either an Array that represents the order in which attributes are concatenated to composite attributes the key, or a String for a composite attribute template. (see [Composite Attributes](#composite-attributes) below for more on this functionality).
+| `sk.composite` | `string[]`                             | no       | Either an Array that represents the order in which attributes are concatenated to composite attributes the key, or a String for a composite attribute template. (see [Composite Attributes](#composite-attributes) below for more on this functionality).
 | `sk.template`  | `string`                               | no       | A string that represents the template in which attributes composed to form a key (see [Composite Attribute Templates](#composite-attribute-templates) below for more on this functionality).
 | `sk.field`     | `string`                               | yes      | The name of the attribute as it exists in DynamoDB, if named differently in the schema attributes.
-| `pk.casing`    | `default` | `upper` | `lower` | `none` | no       | Choose a case for ElectroDB to convert your keys to, to avoid casing pitfalls when querying data. Default: `lower`.
+| `pk.casing`    | `default`, `upper`, `lower`, `none`,   | no       | Choose a case for ElectroDB to convert your keys to, to avoid casing pitfalls when querying data. Default: `lower`.
 | `index`        | `string`                               | no       | Required when the `Index` defined is a *Secondary Index*; but is left blank for the table's primary index.
-| `collection`   | `string | string[]`                    | no       | Used when models are joined to a `Service`. When two entities share a `collection` on the same `index`, they can be queried with one request to DynamoDB. The name of the collection should represent what the query would return as a pseudo `Entity`. (see [Collections](#collections) below for more on this functionality).
+| `collection`   | `string`, `string[]`                   | no       | Used when models are joined to a `Service`. When two entities share a `collection` on the same `index`, they can be queried with one request to DynamoDB. The name of the collection should represent what the query would return as a pseudo `Entity`. (see [Collections](#collections) below for more on this functionality).
 
 ### Indexes Without Sort Keys
 When using indexes without Sort Keys, that should be expressed as an index *without* an `sk` property at all. Indexes without an `sk` cannot have a collection, see [Collections](#collections) for more detail.
@@ -1465,7 +1474,7 @@ When your attribute's name, or [`field` property](#expanded-syntax) on an attrib
 }
 ```
 
-[![Try it out!](https://img.shields.io/badge/electrodb-try_out_this_example_›-%23f9bd00?style=for-the-badge&logo=amazondynamodb&labelColor=1a212a)](JYWwDg9gTgLgBAbzgUQHY2DAnnAvnAMyghDgCIBTAGwoGMZiATAIzIG4AoD2iVAZ3jBUANwrpoOALxxUFAO4p0mLAAoEHOJrggIjagC5EGrSbEZshslggBXKAH0zy)
+[![Try it out!](https://img.shields.io/badge/electrodb-try_out_this_example_›-%23f9bd00?style=for-the-badge&logo=amazondynamodb&labelColor=1a212a)](https://electrodb.fun/?#code/JYWwDg9gTgLgBAbwKIDsbBgTwL5wGZQQhwDkApgDZkDGMhAJgEYkDcAUG9RCgM7zAoAbmTTRMcALxwUZAO5xU6LAAoEbOHBAR6lAFyJ1GuCKWZ9AIkwQArlAD6JjJjsoAhiDLmANIY08yUILA1GQWVrZ2-oHBZC7unj5GcMJQPMDcFgCM5obYiXCuMHTAjNYwZDz6akmu1FzWaACS9FW+RlhgoXDmfFACAOY5SXltYAzWtABy1iCMAa1JGh1d5igzc1BDRti5+QI6AB4VC0Zj2hMwlQaLcGAA1ic3eMCULd219U303m1JXOAQNLlfQAbXMHxsX3MAF1fnARjceA9rjd8C8KG9zGd6BdprMAj9UXB-pAgV0wdjcesCbCbjthrk2HlEDBXIwqPoSCBMAAVNlUEjYACU7E43D4BTqkJgzUk7zqMAAtAAWACsAGYAAzmdhcXjwSlTalQOUAJk1msyooEwlEUEwhgAdGAyqpJZ8ZfQvLdxkb8SbhU7+hBlCKODaTGJHQBHawBB1JZ2+y6qCENT2BxPB0PsIA)
 
 **Using `template`** 
 
@@ -5616,11 +5625,62 @@ let storeId = "LatteLarrys";
 let stores = await StoreLocations.malls({mallId}).query({buildingId, storeId}).go();
 ```
 
-# Exported TypeScript Types
+# TypeScript
+ElectroDB using advanced dynamic typing techniques to automatically create types based on the configurations in your model. Changes to your model will automatically change the types returned by ElectroDB.
+
+## Custom Attributes
+If you have a need for a custom attribute type (beyond those supported by ElectroDB) you can use the the export function `createCustomAttribute`. This function takes an attribute definition and allows you to specify a custom typed attribute with ElectroDB:
+
+> _NOTE: creating a custom type, ElectroDB will enforce attribute constraints based on the attribute definition provided, but will yield typing control to the user. This may result in some mismatches between your typing and the constraints enforced by ElectroDB._
+
+```typescript
+import { Entity, createCustomAttribute } from 'electrodb';
+
+type PersonnelRole = {
+    type: 'employee';
+    startDate: string;
+    endDate?: string;
+} | {
+    type: 'contractor';
+    contractStartDate: string;
+    contractEndDate: string;
+};
+
+const table = 'workplace_table';
+const person = new Entity({
+    model: {
+        entity: 'personnel',
+        service: 'workplace',
+        version: '1'
+    },
+    attributes: {
+        id: {
+            type: 'string'
+        },
+        role: createCustomAttribute<PersonnelRole>({
+            required: true,
+        }),
+    },
+    indexes: {
+        record: {
+            pk: {
+                field: 'pk',
+                compose: ['id']
+            },
+            sk: {
+                field: 'sk',
+                compose: [],
+            }
+        }
+    }
+}, { table });
+```
+
+## Exported Types
 
 The following types are exported for easier use while using ElectroDB with TypeScript:
 
-## EntityRecord Type
+### EntityRecord Type
 
 The EntityRecord type is an object containing every attribute an Entity's model.
 
@@ -5638,7 +5698,7 @@ _Use:_
 type EntiySchema = EntityRecord<typeof MyEntity>
 ```
 
-## EntityItem Type
+### EntityItem Type
 
 This type represents an item as it is returned from a query. This is different from the `EntityRecord` in that this type reflects the `required`, `hidden`, `default`, etc properties defined on the attribute.
 
@@ -5657,7 +5717,7 @@ _Use:_
 type Thing = EntityItem<typeof MyEntityInstance>;
 ```
 
-## CollectionItem Type
+### CollectionItem Type
 
 This type represents the value returned from a collection query, and is similar to EntityItem.
 
@@ -5667,7 +5727,7 @@ _Use:_
 type CollectionResults = CollectionItem<typeof MyServiceInstance, "collectionName">
 ``` 
 
-## CreateEntityItem Type
+### CreateEntityItem Type
 
 This type represents an item that you would pass your entity's `put` or `create` method
 
@@ -5686,7 +5746,7 @@ _Use:_
 type NewThing = CreateEntityItem<typeof MyEntityInstance>;
 ```
 
-## UpdateEntityItem Type
+### UpdateEntityItem Type
 
 This type represents an item that you would pass your entity's `set` method when using `create` or `update`.
 
@@ -5705,8 +5765,7 @@ _Use:_
 type UpdateProperties = UpdateEntityItem<typeof MyEntityInstance>;
 ```
 
-
-## UpdateAddEntityItem Type
+### UpdateAddEntityItem Type
 
 This type represents an item that you would pass your entity's `add` method when using `create` or `update`.
 
@@ -5719,7 +5778,7 @@ export type UpdateAddEntityItem<E extends Entity<any, any, any, any>> =
 
 `````
 
-## UpdateSubtractEntityItem Type
+### UpdateSubtractEntityItem Type
 
 This type represents an item that you would pass your entity's `subtract` method when using `create` or `update`.
 
@@ -5731,7 +5790,7 @@ export type UpdateSubtractEntityItem<E extends Entity<any, any, any, any>> =
         : never;
 ```
 
-## UpdateAppendEntityItem Type
+### UpdateAppendEntityItem Type
 
 This type represents an item that you would pass your entity's `append` method when using `create` or `update`.
 
@@ -5743,7 +5802,7 @@ export type UpdateAppendEntityItem<E extends Entity<any, any, any, any>> =
         : never;
 ```
 
-## UpdateRemoveEntityItem Type
+### UpdateRemoveEntityItem Type
 
 This type represents an item that you would pass your entity's `remove` method when using `create` or `update`.
 
@@ -5755,7 +5814,7 @@ export type UpdateRemoveEntityItem<E extends Entity<any, any, any, any>> =
         : never;
 ```
 
-## UpdateDeleteEntityItem Type
+### UpdateDeleteEntityItem Type
 
 This type represents an item that you would pass your entity's `delete` method when using `create` or `update`.
 

package/index.d.ts

@@ -1,3 +1,4 @@
+
 export type DocumentClientMethod = (parameters: any) => {promise: () => Promise<any>};
 
 export type DocumentClient = {
@@ -848,7 +849,6 @@ export interface NestedEnumAttribute {
     readonly label?: string;
 }
 
-
 export interface EnumAttribute {
     readonly type: ReadonlyArray<string>;
     readonly required?: boolean;
@@ -1032,6 +1032,60 @@ export interface NestedStringSetAttribute {
     readonly field?: string;
 }
 
+export interface NestedEnumNumberSetAttribute {
+    readonly type: "set";
+    readonly items: ReadonlyArray<number>;
+    readonly required?: boolean;
+    readonly hidden?: boolean;
+    readonly readOnly?: boolean;
+    readonly get?: (val: Array<number>, item: any) => Array<number> | undefined | void;
+    readonly set?: (val?: Array<number>, item?: any) => Array<number> | undefined | void;
+    readonly default?: Array<number> | (() => Array<number>);
+    readonly validate?: ((val: Array<number>) => boolean) | ((val: Array<number>) => void) | ((val: Array<number>) => string | void) | RegExp;
+    readonly field?: string;
+}
+
+export interface EnumNumberSetAttribute {
+    readonly type: "set";
+    readonly items: ReadonlyArray<number>;
+    readonly required?: boolean;
+    readonly hidden?: boolean;
+    readonly readOnly?: boolean;
+    readonly get?: (val: Array<number>, item: any) => Array<number> | undefined | void;
+    readonly set?: (val?: Array<number>, item?: any) => Array<number> | undefined | void;
+    readonly default?: Array<number> | (() => Array<number>);
+    readonly validate?: ((val: Array<number>) => boolean) | ((val: Array<number>) => void) | ((val: Array<number>) => string | void) | RegExp;
+    readonly field?: string;
+    readonly watch?: ReadonlyArray<string> | "*";
+}
+
+export interface NestedEnumStringSetAttribute {
+    readonly type: "set";
+    readonly items: ReadonlyArray<string>;
+    readonly required?: boolean;
+    readonly hidden?: boolean;
+    readonly readOnly?: boolean;
+    readonly get?: (val: Array<string>, item: any) => Array<string> | undefined | void;
+    readonly set?: (val?: Array<string>, item?: any) => Array<string> | undefined | void;
+    readonly default?: Array<string> | (() => Array<string>);
+    readonly validate?: ((val: Array<string>) => boolean) | ((val: Array<string>) => void) | ((val: Array<string>) => string | void) | RegExp;
+    readonly field?: string;
+}
+
+export interface EnumStringSetAttribute {
+    readonly type: "set";
+    readonly items: ReadonlyArray<string>;
+    readonly required?: boolean;
+    readonly hidden?: boolean;
+    readonly readOnly?: boolean;
+    readonly get?: (val: Array<string>, item: any) => Array<string> | undefined | void;
+    readonly set?: (val?: Array<string>, item?: any) => Array<string> | undefined | void;
+    readonly default?: Array<string> | (() => Array<string>);
+    readonly validate?: ((val: Array<string>) => boolean) | ((val: Array<string>) => void) | ((val: Array<string>) => string | void) | RegExp;
+    readonly field?: string;
+    readonly watch?: ReadonlyArray<string> | "*";
+}
+
 export interface StringSetAttribute {
     readonly type: "set";
     readonly items: "string";
@@ -1073,6 +1127,25 @@ export interface NumberSetAttribute {
     readonly watch?: ReadonlyArray<string> | "*";
 }
 
+type StaticAttribute = {
+    readonly type: "static";
+    readonly hidden?: boolean;
+    value: string | number | boolean;
+    readonly field?: string;
+}
+
+type CustomAttribute<T extends any = any> = {
+    readonly type: "custom";
+    readonly [CustomAttributeSymbol]: T;
+    readonly hidden?: boolean;
+    readonly get?: (val: T, item: any) => T | undefined | void;
+    readonly set?: (val?: T, item?: any) => T | undefined | void;
+    readonly default?: T | (() => T);
+    readonly validate?: ((val: T) => boolean) | ((val: T) => void) | ((val: T) => string | void);
+    readonly field?: string;
+    readonly watch?: ReadonlyArray<string> | "*";
+};
+
 export type Attribute =
     BooleanAttribute
     | NumberAttribute
@@ -1084,7 +1157,11 @@ export type Attribute =
     | NumberSetAttribute
     | StringListAttribute
     | NumberListAttribute
-    | MapListAttribute;
+    | MapListAttribute
+    | StaticAttribute
+    | CustomAttribute
+    | EnumNumberSetAttribute
+    | EnumStringSetAttribute;
 
 export type NestedAttributes =
     NestedBooleanAttribute
@@ -1097,7 +1174,10 @@ export type NestedAttributes =
     | NestedMapListAttribute
     | NestedStringSetAttribute
     | NestedNumberSetAttribute
-    | NestedEnumAttribute;
+    | NestedEnumAttribute
+    | NestedEnumAttribute
+    | NestedEnumNumberSetAttribute
+    | NestedEnumStringSetAttribute;
 
 export interface IndexWithSortKey {
     readonly sk: {
@@ -1171,7 +1251,9 @@ type PartialDefinedKeys<T> = {
 }
 
 export type ItemAttribute<A extends Attribute> =
-    A["type"] extends infer R
+    A extends CustomAttribute<infer T>
+        ? T
+    : A["type"] extends infer R
         ? R extends "string" ? string
         : R extends "number" ? number
             : R extends "boolean" ? boolean
@@ -1200,7 +1282,8 @@ export type ItemAttribute<A extends Attribute> =
                                     ? A["items"] extends infer I
                                         ? I extends "string" ? string[]
                                             : I extends "number" ? number[]
-                                                : never
+                                                : I extends ReadonlyArray<infer ENUM> ? ENUM[]
+                                                    : never
                                         : never
                                     : never
                                 : R extends "any" ? any
@@ -1208,8 +1291,11 @@ export type ItemAttribute<A extends Attribute> =
         : never
 
 export type ReturnedAttribute<A extends Attribute> =
-    A["type"] extends infer R
-        ? R extends "string" ? string
+    A extends CustomAttribute<infer T>
+    ? T
+    : A["type"] extends infer R
+        ? R extends "static" ? never
+        : R extends "string" ? string
         : R extends "number" ? number
             : R extends "boolean" ? boolean
                 : R extends ReadonlyArray<infer E> ? E
@@ -1251,7 +1337,8 @@ export type ReturnedAttribute<A extends Attribute> =
                                     ? A["items"] extends infer I
                                         ? I extends "string" ? string[]
                                             : I extends "number" ? number[]
-                                                : never
+                                                : I extends ReadonlyArray<infer ENUM> ? ENUM[]
+                                                    : never
                                         : never
                                     : never
                                 : R extends "any" ? any
@@ -1259,8 +1346,11 @@ export type ReturnedAttribute<A extends Attribute> =
         : never
 
 export type CreatedAttribute<A extends Attribute> =
-    A["type"] extends infer R
-        ? R extends "string" ? string
+    A extends CustomAttribute<infer T>
+        ? T
+        : A["type"] extends infer R
+        ? R extends "static" ? never
+        : R extends "string" ? string
         : R extends "number" ? number
             : R extends "boolean" ? boolean
                 : R extends ReadonlyArray<infer E> ? E
@@ -1302,7 +1392,8 @@ export type CreatedAttribute<A extends Attribute> =
                                     ? A["items"] extends infer I
                                         ? I extends "string" ? string[]
                                             : I extends "number" ? number[]
-                                                : never
+                                                : I extends ReadonlyArray<infer ENUM> ? ENUM[]
+                                                    : never
                                         : never
                                     : never
                                 : R extends "any" ? any
@@ -1318,10 +1409,13 @@ export type CreatedItem<A extends string, F extends string, C extends string, S
 }
 
 export type EditableItemAttribute<A extends Attribute> =
-    A extends ReadOnlyAttribute
+    A extends CustomAttribute<infer T>
+    ? T
+    : A extends ReadOnlyAttribute
         ? never
         : A["type"] extends infer R
-        ? R extends "string" ? string
+            ? R extends "static" ? never
+                : R extends "string" ? string
             : R extends "number" ? number
                 : R extends "boolean" ? boolean
                     : R extends ReadonlyArray<infer E> ? E
@@ -1353,7 +1447,8 @@ export type EditableItemAttribute<A extends Attribute> =
                                         ? A["items"] extends infer I
                                             ? I extends "string" ? string[]
                                                 : I extends "number" ? number[]
-                                                    : never
+                                                    : I extends ReadonlyArray<infer ENUM> ? ENUM[]
+                                                        : never
                                             : never
                                         : never
                                     : R extends "any" ? any
@@ -1361,10 +1456,13 @@ export type EditableItemAttribute<A extends Attribute> =
         : never
 
 export type UpdatableItemAttribute<A extends Attribute> =
-    A extends ReadOnlyAttribute
+    A extends CustomAttribute<infer T>
+        ? T
+        : A extends ReadOnlyAttribute
         ? never
         : A["type"] extends infer R
-        ? R extends "string" ? string
+            ? R extends "static" ? never
+                : R extends "string" ? string
             : R extends "number" ? number
                 : R extends "boolean" ? boolean
                     : R extends ReadonlyArray<infer E> ? E
@@ -1411,7 +1509,8 @@ export type UpdatableItemAttribute<A extends Attribute> =
                                         ? A["items"] extends infer I
                                             ? I extends "string" ? string[]
                                                 : I extends "number" ? number[]
-                                                    : never
+                                                    : I extends ReadonlyArray<infer ENUM> ? ENUM[]
+                                                        : never
                                             : never
                                         : never
                                     : R extends "any" ? any
@@ -1419,10 +1518,13 @@ export type UpdatableItemAttribute<A extends Attribute> =
         : never
 
 export type RemovableItemAttribute<A extends Attribute> =
-    A extends ReadOnlyAttribute | RequiredAttribute
+    A extends CustomAttribute<infer T>
+        ? T
+        : A extends ReadOnlyAttribute | RequiredAttribute
         ? never
         : A["type"] extends infer R
-        ? R extends "string" ? string
+            ? R extends "static" ? never
+                : R extends "string" ? string
             : R extends "number" ? number
                 : R extends "boolean" ? boolean
                     : R extends ReadonlyArray<infer E> ? E
@@ -1454,7 +1556,8 @@ export type RemovableItemAttribute<A extends Attribute> =
                                         ? A["items"] extends infer I
                                             ? I extends "string" ? string[]
                                                 : I extends "number" ? number[]
-                                                    : never
+                                                    : I extends ReadonlyArray<infer ENUM> ? ENUM[]
+                                                        : never
                                             : never
                                         : never
                                     : R extends "any" ? any
@@ -1599,7 +1702,7 @@ export type RemoveItem<A extends string, F extends string, C extends string, S e
 export type AppendItem<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> =
     {
         [
-        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends 'list' | 'any'
+        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends 'list' | 'any' | 'custom'
             ? P
             : never
         ]?: P extends keyof SetItem<A,F,C,S>
@@ -1610,7 +1713,7 @@ export type AppendItem<A extends string, F extends string, C extends string, S e
 export type AddItem<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> =
     {
         [
-        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends "number" | "any" | "set"
+        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends 'number' | 'any' | 'set' | 'custom'
             ? P
             : never
         ]?: P extends keyof SetItem<A,F,C,S>
@@ -1621,7 +1724,7 @@ export type AddItem<A extends string, F extends string, C extends string, S exte
 export type SubtractItem<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> =
     {
         [
-        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends "number" | "any"
+        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends 'number' | 'any' | 'custom'
             ? P
             : never
         ]?: P extends keyof SetItem<A,F,C,S>
@@ -1632,7 +1735,7 @@ export type SubtractItem<A extends string, F extends string, C extends string, S
 export type DeleteItem<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> =
     {
         [
-        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends "any" | "set"
+        P in keyof ItemTypeDescription<A,F,C,S> as ItemTypeDescription<A,F,C,S>[P] extends 'any' | 'set' | 'custom'
             ? P
             : never
         ]?: P extends keyof SetItem<A,F,C,S>
@@ -1642,6 +1745,7 @@ export type DeleteItem<A extends string, F extends string, C extends string, S e
 
 export declare const WhereSymbol: unique symbol;
 export declare const UpdateDataSymbol: unique symbol;
+export declare const CustomAttributeSymbol: unique symbol;
 
 export type WhereAttributeSymbol<T extends any> =
         { [WhereSymbol]: void }
@@ -1821,4 +1925,18 @@ export class Service<E extends {[name: string]: Entity<any, any, any, any>}> {
     entities: E;
     collections: CollectionQueries<E, CollectionAssociations<E>>
     constructor(entities: E, config?: ServiceConfiguration);
-}
+}
+
+type CustomAttributeDefinition<T> = {
+    readonly required?: boolean;
+    readonly hidden?: boolean;
+    readonly readOnly?: boolean;
+    readonly get?: (val: T, item: any) => T | undefined | void;
+    readonly set?: (val?: T, item?: any) => T | undefined | void;
+    readonly default?: T | (() => T);
+    readonly validate?: ((val: T) => boolean) | ((val: T) => void) | ((val: T) => string | void);
+    readonly field?: string;
+    readonly watch?: ReadonlyArray<string> | "*";
+}
+
+declare function createCustomAttribute<T>(definition?: CustomAttributeDefinition<T>): CustomAttribute<T>;

package/index.js

@@ -1,4 +1,5 @@
 const { Entity } = require("./src/entity");
 const { Service } = require("./src/service");
+const { createCustomAttribute } = require('./src/schema');
 
-module.exports = { Entity, Service };
+module.exports = { Entity, Service, createCustomAttribute };

package/notes

@@ -0,0 +1,45 @@
+/*
+
+todo: better param typing
+done: get typing
+todo: get implementation
+done: get[] typing
+todo: get[] implementation
+done: delete typing
+todo: delete implementation
+done: delete[] typing
+todo: delete[] implementation
+done: put[] typing
+todo: put[] implementation
+done: put typing
+todo: put implementation
+todo: update typing
+done: update implementation
+    done: SetRecord
+    done: RemoveRecord
+    done: DataUpdateMethodRecord
+
+done: scan typing
+todo: scan implementation
+done: query typing
+todo: query implementation
+done: find typing
+todo: find implementation
+done: match typing
+todo: match implementation
+done: parse typing
+todo: parse implementation (requires cursor?)
+todo: collection query
+todo: collection impl
+
+todo: add where to go?
+todo: rethink option names
+
+todo: add cursor to query options
+todo: remove old doc notes on `join` and slim down `service`
+
+
+
+find and test any add on set and number
+try number enum?
+integration test enum set ts