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.

If you experience any issues using TypeScript with ElectroDB, your feedback is very important, please create a GitHub issue, and it can be addressed.

Type Utilities

ElectroDB exports some functions to assist with the creation of custom types and/or to improve type portability.

CustomAttributeType

The function CustomAttributeType assists in the creation of custom attributes. This can be helpful to extend the primitive types and/or build complex union types. Check out the recipe Opaque Types to learn more by example.

createSchema

The createSchema function allows you to define a schema independent of instantiating a new entity. This can be useful if the model definition needs to be portable or dynamic. This function will also validate your schema, and will throw if it is not a valid format.

Try it out!

Exported Types

The following types are exported for easier use while using ElectroDB with TypeScript. The naming convention for the types include three different kinds:

  • xResponse — Types with the postfix Response represent the returned interfaces directly from ElectroDB.

  • xItem — Types with the postfix Item represent an Entity row. Queries return multiple items, a get returns a single item, etc. The type for an item is inferred based on the attributes and index definitions within your model. For example if your attribute is marked as required then that attribute will never be undefined, if your attribute has a default value then it won’t be required to be supplied on put, list attributes must be an array, etc.

  • xRecord — In some cases it is helpful to have a type that represents all attributes of an item without nullable properties. Types with the postfix Record contain all properties in a non-nullable format.

The follow highlight many of the types exported utility types from ElectroDB:

QueryResponse Type

The QueryResponse type is the same type returned by an ElectroDB Query.

Definition:

export type QueryResponse<E extends Entity<any, any, any, any>> = {
  data: EntityItem<E>;
  cursor: string | null;
};

Usage:

type EntitySchema = QueryResponse<typeof MyEntity>;

EntityIdentifiers Type

The EntityIdentifiers type an object containing each of your Entity’s Primary Index composite attributes. It is the object used by get, update, patch, delete, and remove to uniquely identify an item.

Definition:

export type EntityIdentifiers<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? AllTableIndexCompositeAttributes<A, F, C, S>
    : never;

Usage:

type Keys = EntityIdentifiers<typeof MyEntity>;

EntityRecord Type

The EntityRecord type is an object containing every attribute an Entity’s model.

Definition:

type EntityRecord<E extends Entity<any, any, any, any>> = E extends Entity<
  infer A,
  infer F,
  infer C,
  infer S
>
  ? Item<A, F, C, S, S["attributes"]>
  : never;

Usage:

type Item = EntityRecord<typeof MyEntity>;

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.

Definition:

export type EntityItem<E extends Entity<any, any, any, any>> = E extends Entity<
  infer A,
  infer F,
  infer C,
  infer S
>
  ? ResponseItem<A, F, C, S>
  : never;

Usage:

type Item = EntityItem<typeof MyEntityInstance>;

CollectionItem Type

This type represents an item returned from a collection query, and is similar to EntityItem.

Definition:

export type CollectionItem<
  SERVICE extends Service<any>,
  COLLECTION extends keyof SERVICE["collections"],
> = SERVICE extends Service<infer E>
  ? Pick<
      {
        [EntityName in keyof E]: E[EntityName] extends Entity<
          infer A,
          infer F,
          infer C,
          infer S
        >
          ? COLLECTION extends keyof CollectionAssociations<E>
            ? EntityName extends CollectionAssociations<E>[COLLECTION]
              ? ResponseItem<A, F, C, S>[]
              : never
            : never
          : never;
      },
      COLLECTION extends keyof CollectionAssociations<E>
        ? CollectionAssociations<E>[COLLECTION]
        : never
    >
  : never;

Usage:

type CollectionResults = CollectionItem<
  typeof MyServiceInstance,
  "collectionName"
>;

CollectionResponse

This type represents the value returned the collection query itself

Definition:

export type CollectionResponse<
  SERVICE extends Service<any>,
  COLLECTION extends keyof SERVICE["collections"],
> = {
  data: CollectionItem<SERVICE, COLLECTION>;
  cursor: string | null;
};

Usage:

type CollectionResults = CollectionResponse<
  typeof MyServiceInstance,
  "collectionName"
>;

CreateEntityItem Type

This type represents an item that you would pass your entity’s put or create method

Definition:

export type CreateEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? PutItem<A, F, C, S>
    : never;

Usage:

type NewThing = CreateEntityItem<typeof MyEntityInstance>;

UpdateEntityItem Type

This type represents an item that you would pass your entity’s set method when using create or update.

Definition:

export type UpdateEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? SetItem<A, F, C, S>
    : never;

Usage:

type UpdateProperties = UpdateEntityItem<typeof MyEntityInstance>;

UpdateAddEntityItem Type

This type represents an item that you would pass your entity’s add method when using create or update.

Definition:

export type UpdateAddEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? AddItem<A, F, C, S>
    : never;

UpdateSubtractEntityItem Type

This type represents an item that you would pass your entity’s subtract method when using create or update.

Definition:

export type UpdateSubtractEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? SubtractItem<A, F, C, S>
    : never;

UpdateAppendEntityItem Type

This type represents an item that you would pass your entity’s append method when using create or update.

Definition:

export type UpdateAppendEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? AppendItem<A, F, C, S>
    : never;

UpdateRemoveEntityItem Type

This type represents an item that you would pass your entity’s remove method when using create or update.

Definition:

export type UpdateRemoveEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? RemoveItem<A, F, C, S>
    : never;

UpdateDeleteEntityItem Type

This type represents an item that you would pass your entity’s delete method when using create or update.

Definition:

export type UpdateDeleteEntityItem<E extends Entity<any, any, any, any>> =
  E extends Entity<infer A, infer F, infer C, infer S>
    ? DeleteItem<A, F, C, S>
    : never;