API Overview

create functions

createState()

Creates a state for a store.

/**
 * Creates a state object for a store.
 * @template TStore - The store type.
 * @template TGenericStore - The generic store type.
 * @param state - The state object.
 */
export function createState<
  TStore extends Store,
TGenericStore extends Store = Store,
>(
  state: {
    [K in keyof (Omit<ExtractStore<TStore>['state'], keyof ExtractStore<TGenericStore>['state']> & Partial<ExtractStore<TGenericStore>['state']>)]:
    (Omit<ExtractStore<TStore>['state'], keyof ExtractStore<TGenericStore>['state']> & Partial<ExtractStore<TGenericStore>['state']>)[K] | undefined;
  },
): ExtractStore<TStore>['state'] {
  return state
}

createGetters()

Creates getters for a store.

/**
 * Creates a getters object for a store.
 * @template TStore - The store type.
 * @template TGenericStore - The generic store type.
 * @param getters - The getters object.
 */
export function createGetters<
  TStore extends Store,
TGenericStore extends Store = Store,
>(
  getters: PiniaGetterThis<TStore, TGenericStore>,
): ExtractStore<TStore>['getters'] {
  return getters
}

createActions()

Creates actions for a store.

/**
 * Creates an actions object for a store.
 * @template TStore - The store type.
 * @template TGenericStore - The generic store type.
 * @param actions - The actions object.
 */
export function createActions<
  TStore extends Store,
TGenericStore extends Store = Store,
>(
  actions: PiniaActionThis<TStore, TGenericStore>,
): ExtractStore<TStore>['actions'] {
  return actions
}

define functions

defineGenericStore()

Defines a generic store with the given state, getters, and actions.

/**
 * Defines a generic store.
 * @template TStore - The store type.
 * @param store - The store object.
 * @param baseStore - Another base store to extend.
 */
export function defineGenericStore<
  TStore extends Store,
TGenericStore extends Store = Store,
>(
  store: StoreThis<TStore, TGenericStore>,
  baseStore: StoreThis<TGenericStore> = {},
): StoreThis<TStore> {
  const undefinedProps = new Set<string>()

  store = filterUndefined(store, undefinedProps)
  baseStore = filterUndefined(baseStore, undefinedProps)

  return {
    state: {
      ...baseStore?.state,
      ...store?.state,
    },
    getters: {
      ...baseStore?.getters,
      ...store?.getters,
    },
    actions: {
      ...baseStore?.actions,
      ...store?.actions,
    },
    options: {
      ...baseStore?.options,
      ...store?.options,
    },
  }
}

useStore()

Where the actual Pinia store is created. Combines the given store with a generic store.

/**
 * Defines a store. Can extend a generic store.
 * @template TStore - The store type.
 * @template TGenericStore - The generic store type.
 * @param id - The store id.
 * @param store - The store object.
 * @param genericStore - The generic store object.
 */
export function useStore<
  TStore extends Store,
TGenericStore extends Store = Store,
>(
  id: TStore['$id'],
  store: StoreThis<TStore, TGenericStore>,
  genericStore: StoreThis<TGenericStore> = {},
) {
  const undefinedProps = new Set<string>()

  store = filterUndefined(store, undefinedProps)
  genericStore = filterUndefined(genericStore, undefinedProps)

  return defineStore(id, {
    state: () => ({
      ...genericStore.state,
      ...store.state,
    }),
    getters: {
      ...genericStore.getters,
      ...store.getters,
    },
    actions: {
      ...genericStore.actions,
      ...store.actions,
    },
    ...genericStore.options,
    ...store.options,
  }) as StoreDefinition<
    TStore['$id'],
    ExtractStore<TStore>['state'],
    ExtractStore<TStore>['getters'],
    ExtractStore<TStore>['actions']
  >
}

Types

PiniaStore<>

Creates a type for a store or a generic store.

/**
 * Define a type for a store or a generic store. Combines their properties.
 * @template Id - The store ID.
 * @template State - The store state.
 * @template Getters - The store getters.
 * @template Actions - The store actions.
 * @template TGenericStore - The generic store type.
 * @public
 */
export type PiniaStore<
  Id extends string = string,
  State extends StateTree = object,
  Getters = object,
  Actions = object,
  TGenericStore extends Store = Store,
> = Store<
  Id,
  State & ExtractStore<TGenericStore>['state'],
  Getters & ExtractStore<TGenericStore>['getters'],
  Actions & ExtractStore<TGenericStore>['actions']
>

Internal types

ExtractStore<>

Extracts the type of a store.

/**
 * Extracts the state, getters and actions from a store.
 * @template TStore - The store type.
 * @example
 * Index this type to access the state, getters and actions of a store.
 * ```ts
 * type State = ExtractStore<Store>['state']
 * ```
 * @internal
 */
export type ExtractStore<TStore extends Store> = TStore extends Store<
  string,
  infer S extends StateTree,
  infer G,
  infer A
>
  ? {
      state: S
      getters: G
      actions: A
    }
  : never

PiniaGetterThis<>

Type for getters that use this to access the store.

/**
 * Getters with `this` context of the store and the generic store combined.
 * Puts all of the properties into `this`, while it only requires the getters unique to the store to be defined.
 * @internal
 */
export type PiniaGetterThis<TStore extends Store, TGenericStore extends Store = TStore> = {
  [K in keyof (Omit<ExtractStore<TStore>['getters'], keyof ExtractStore<TGenericStore>['getters']> & Partial<ExtractStore<TGenericStore>['getters']>)]?:
  ((this: TStore & NoId<TGenericStore>) => ExtractStore<TStore>['getters'][K] extends (...args: any[]) => any ? ReturnType<ExtractStore<TStore>['getters'][K]> : never) | undefined
}

PiniaActionThis<>

Type for actions that use this to access the store.

/**
 * Actions with `this` context of the store and the generic store combined.
 * Puts all of the properties into `this`, while it only requires the actions unique to the store to be defined.
 * @internal
 */
export type PiniaActionThis<TStore extends Store, TGenericStore extends Store = TStore> = {
  [K in keyof (Omit<ExtractStore<TStore>['actions'], keyof ExtractStore<TGenericStore>['actions']> & Partial<ExtractStore<TGenericStore>['actions']>)]?:
  ((this: TStore & NoId<TGenericStore>, ...args: ExtractStore<TStore>['actions'][K] extends (...args: any[]) => any ? Parameters<ExtractStore<TStore>['actions'][K]> : never)
  => ExtractStore<TStore>['actions'][K] extends (...args: any[]) => any ? ReturnType<ExtractStore<TStore>['actions'][K]> : never) | undefined
}

StoreThis<>

Type that combines PiniaGetterThis and PiniaActionThis with the state.

/**
 * Store with `this` context of the store and the generic store combined.
 * Puts all of the properties into `this`, while it only requires the ones unique to the store to be defined.
 * @internal
 */
export interface StoreThis<TStore extends Store, TGenericStore extends Store = Store> {
  state?: {
    [K in keyof (Omit<ExtractStore<TStore>['state'], keyof ExtractStore<TGenericStore>['state']> & Partial<ExtractStore<TGenericStore>['state']>)]?:
    (Omit<ExtractStore<TStore>['state'], keyof ExtractStore<TGenericStore>['state']> & Partial<ExtractStore<TGenericStore>['state']>)[K] | undefined;
  }
  getters?: PiniaGetterThis<TStore, TGenericStore>
  actions?: PiniaActionThis<TStore, TGenericStore>
  // options?: Omit<DefineStoreOptions<TStore['$id'], TStore['$state'], ExtractStore<TStore>['getters'], ExtractStore<TStore>['actions']>, 'id'>
  options?: DefineStoreOptionsBase<ExtractStore<TStore>['state'], TStore>
}