#

API Docs for: v3.16.0-alpha.2
Show: Inherited Protected Private Deprecated

# File: ../store/addon/-private/ts-interfaces/identifier.ts

    /**
      @module @ember-data/store
    */
    import { symbol } from '../ts-interfaces/utils/symbol';

    // provided for additional debuggability
    export const DEBUG_CLIENT_ORIGINATED: unique symbol = symbol('record-originated-on-client');
    export const DEBUG_IDENTIFIER_BUCKET: unique symbol = symbol('identifier-bucket');

    export interface Identifier {
      lid: string;
      clientId?: string;
    }

    /**
     * An Identifier specific to a record which may or may not
     * be present in the cache.
     *
     * The absence of an `id` DOES NOT indicate that this
     * Identifier is for a new client-created record as it
     * may also indicate that it was generated for a secondary
     * index and the primary `id` index is not yet known.
     */
    export interface RecordIdentifier extends Identifier {
      id: string | null;
      type: string;
    }

    /**
     * Used when an Identifier is known to be the stable version
     *
     * @internal
     */
    export interface StableIdentifier extends Identifier {
      [DEBUG_IDENTIFIER_BUCKET]?: string;
    }

    /**
     * Used when a RecordIdentifier is known to be the stable version
     *
     * @internal
     */
    export interface StableRecordIdentifier extends StableIdentifier {
      id: string | null;
      type: string;
      [DEBUG_CLIENT_ORIGINATED]?: boolean;
    }

    /**
      A method which can expect to receive various data as its first argument
      and the name of a bucket as its second argument. Currently the second
      argument will always be `record` data should conform to a `json-api`
      `Resource` interface, but will be the normalized json data for a single
      resource that has been given to the store.

      The method must return a unique (to at-least the given bucket) string identifier
      for the given data as a string to be used as the `lid` of an `Identifier` token.

      This method will only be called by either `getOrCreateRecordIdentifier` or
      `createIdentifierForNewRecord` when an identifier for the supplied data
      is not already known via `lid` or `type + id` combo and one needs to be
      generated or retrieved from a proprietary cache.

      `data` will be the same data argument provided to `getOrCreateRecordIdentifier`
      and in the `createIdentifierForNewRecord` case will be an object with
      only `type` as a key.
    */
    export type GenerationMethod = (data: Object, bucket: string) => string;

    /*
     A method which can expect to receive an existing `Identifier` alongside
     some new data to consider as a second argument. This is an opportunity
     for secondary lookup tables and caches associated with the identifier
     to be amended.

     This method is called everytime `updateRecordIdentifier` is called and
      with the same arguments. It provides the opportunity to update secondary
      lookup tables for existing identifiers.

     It will always be called after an identifier created with `createIdentifierForNewRecord`
      has been committed, or after an update to the `record` a `RecordIdentifier`
      is assigned to has been committed. Committed here meaning that the server
      has acknowledged the update (for instance after a call to `.save()`)

     If `id` has not previously existed, it will be assigned to the `Identifier`
      prior to this `UpdateMethod` being called; however, calls to the parent method
      `updateRecordIdentifier` that attempt to change the `id` or calling update
      without providing an `id` when one is missing will throw an error.
    */
    export type UpdateMethod = (identifier: StableIdentifier, newData: Object, bucket: string) => void;

    /*
    A method which can expect to receive an existing `Identifier` that should be eliminated
     from any secondary lookup tables or caches that the user has populated for it.
    */
    export type ForgetMethod = (identifier: StableIdentifier, bucket: string) => void;

    /*
     A method which can expect to be called when the parent application is destroyed.

     If you have properly used a WeakMap to encapsulate the state of your customization
     to the application instance, you may not need to implement the `resetMethod`.
    */
    export type ResetMethod = () => void;