@dereekb/model 12.1.3 → 12.1.5

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@dereekb/model",
-  "version": "12.1.3",
+  "version": "12.1.5",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
       "node": {
-        "require": "./index.cjs.js",
-        "import": "./index.mjs"
+        "require": "./index.cjs.js"
       },
       "browser": {
         "require": "./index.cjs.js",

package/src/lib/service/index.d.ts

@@ -1,2 +1,3 @@
 export * from './loader';
 export * from './permission';
+export * from './sync';

package/src/lib/service/sync/index.d.ts

@@ -0,0 +1,5 @@
+export * from './sync.entity';
+export * from './sync.entity.synchronizer';
+export * from './sync.entity.synchronizer.basic';
+export * from './sync.source';
+export * from './sync.service';

package/src/lib/service/sync/sync.entity.d.ts

@@ -0,0 +1,63 @@
+import { FactoryWithRequiredInput, Maybe, UniqueModel } from '@dereekb/util';
+import { SyncSourceInfo } from './sync.source';
+/**
+ * A unique identifier for an entity on a specific server.
+ */
+export type SyncEntityId = string;
+/**
+ * A common type for an entity that is shared/used between all systems for an entity that should be synchronized.
+ */
+export type SyncEntityCommonType = string;
+/**
+ * A common identifier for an entity that is shared/used between all systems for an entity that should be synchronized.
+ *
+ * This identifier should be used for retrieving a similar entity from any server.
+ */
+export type SyncEntityCommonId = string;
+/**
+ * A pair of common type and common id for an entity.
+ */
+export interface SyncEntityCommonTypeIdPair {
+    readonly commonType: SyncEntityCommonType;
+    readonly commonId: SyncEntityCommonId;
+}
+export type SyncEntityCommonTypeIdPairFactoryInput = SyncEntityCommonTypeIdPair | SyncEntityCommonId;
+export type SyncEntityCommonTypeIdPairFactory = (input: SyncEntityCommonTypeIdPairFactoryInput) => SyncEntityCommonTypeIdPair;
+export declare function syncEntityCommonTypeIdPairFactory(commonType: SyncEntityCommonType): SyncEntityCommonTypeIdPairFactory;
+/**
+ * Represents a single entity that can be synchronized between different servers.
+ */
+export interface SyncEntity extends UniqueModel, SyncEntityCommonTypeIdPair {
+    /**
+     * The unique identifier for the entity on the server.
+     */
+    readonly id: SyncEntityId;
+    /**
+     * The server information for the entity.
+     */
+    readonly sourceInfo: SyncSourceInfo;
+}
+/**
+ * Configuration for syncEntityFactory().
+ */
+export interface SyncEntityFactoryConfig {
+    /**
+     * The source information to attach to the entity.
+     */
+    readonly sourceInfo: SyncSourceInfo;
+    /**
+     * Optional factory for generating the entity's id from the common id.
+     */
+    readonly idFactory?: Maybe<(commonId: SyncEntityCommonId) => SyncEntityId>;
+}
+/**
+ * Factory for creating a SyncEntity.
+ */
+export type SyncEntityFactory = FactoryWithRequiredInput<SyncEntity, SyncEntityCommonTypeIdPair>;
+/**
+ * Creates a SyncEntityFactory.
+ *
+ * @param config
+ * @returns
+ */
+export declare function syncEntityFactory(config: SyncEntityFactoryConfig): SyncEntityFactory;

package/src/lib/service/sync/sync.entity.synchronizer.basic.d.ts

@@ -0,0 +1,117 @@
+import { Maybe } from '@dereekb/util';
+import { SyncEntityCommonType, SyncEntityCommonTypeIdPair } from './sync.entity';
+import { SyncEntityCommonTypeSynchronizationEntityResult, SyncEntityCommonTypeSynchronizer, SyncEntityCommonTypeSynchronizerSourceContextType, SyncEntityCommonTypeSynchronizerSourceFlowType } from './sync.entity.synchronizer';
+import { SyncSourceClientContext, SyncSourceId, SyncSourceInfo } from './sync.source';
+/**
+ * BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityFunction input
+ */
+export interface BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityFunctionInput {
+    /**
+     * The entity to synchronize.
+     */
+    readonly entityCommonTypeIdPair: SyncEntityCommonTypeIdPair;
+    /**
+     * The determined flow type of this source.
+     */
+    readonly flowType: SyncEntityCommonTypeSynchronizerSourceFlowType;
+    /**
+     * The source for this entity.
+     */
+    readonly source: BasicSyncEntityCommonTypeSynchronizerSource;
+    /**
+     * Additional context information.
+     */
+    readonly context?: Maybe<BasicSyncEntityCommonTypeSynchronizerEntitySourceContext>;
+}
+export interface BasicSyncEntityCommonTypeSynchronizerSourceSyncEntitySynchronizeContext {
+    readonly deleted?: boolean;
+}
+/**
+ * Creates a new BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityInstance for the input.
+ */
+export type BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityFunction = (input: BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityFunctionInput) => Promise<BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityInstance>;
+export type BasicSyncEntityCommonTypeSynchronizerSourceSyncEntitySynchronizeFunction = () => Promise<SyncEntityCommonTypeSynchronizationEntityResult>;
+export interface BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityInstance {
+    /**
+     * Performs the create/update synchronization for the entity.
+     *
+     * The function should typically never throw an error.
+     */
+    readonly synchronize: BasicSyncEntityCommonTypeSynchronizerSourceSyncEntitySynchronizeFunction;
+    /**
+     * Synchronizes the deletion of the entity.
+     *
+     * For a "primary" source, this is called only when another source suggests a delete.
+     *
+     * The function should typically never throw an error.
+     */
+    readonly synchronizeDelete: BasicSyncEntityCommonTypeSynchronizerSourceSyncEntitySynchronizeFunction;
+}
+/**
+ * A declaration of a source for an entity type.
+ *
+ * A BasicSyncEntityCommonTypeSynchronizerSource is considered to be a target for synchronization between the current system/server and the SyncSource.
+ */
+export interface BasicSyncEntityCommonTypeSynchronizerSource {
+    readonly info: SyncSourceInfo;
+    /**
+     * The context type of the source.
+     */
+    readonly contextType: SyncEntityCommonTypeSynchronizerSourceContextType;
+    /**
+     * The default flow type of the source.
+     */
+    readonly defaultFlowType?: Maybe<SyncEntityCommonTypeSynchronizerSourceFlowType>;
+    readonly syncEntityInstance: BasicSyncEntityCommonTypeSynchronizerSourceSyncEntityFunction;
+}
+export type BasicSyncEntityCommonTypeSynchronizer = SyncEntityCommonTypeSynchronizer;
+export interface BasicSyncEntityCommonTypeSynchronizerEntitySourceContextLoaderResult {
+    /**
+     * List of global sources for this entity.
+     */
+    readonly globalSources: (SyncSourceId | BasicSyncEntityCommonTypeSynchronizerEntitySourceGlobalContext)[];
+    /**
+     * List of context sources for this entity.
+     */
+    readonly contextSources: BasicSyncEntityCommonTypeSynchronizerEntitySourceContext[];
+}
+export interface BasicSyncEntityCommonTypeSynchronizerEntitySourceGlobalContext {
+    /**
+     * The source id.
+     */
+    readonly sourceId: SyncSourceId;
+    /**
+     * The flow type of the source. If not defined, will default to the source's default flow type.
+     */
+    readonly flowType?: Maybe<SyncEntityCommonTypeSynchronizerSourceFlowType>;
+}
+export interface BasicSyncEntityCommonTypeSynchronizerEntitySourceContext {
+    readonly sourceId: SyncSourceId;
+    readonly context: SyncSourceClientContext;
+    /**
+     * The flow type of the source. If not defined, will default to the source's default flow type.
+     */
+    readonly flowType?: Maybe<SyncEntityCommonTypeSynchronizerSourceFlowType>;
+}
+/**
+ * Loads source contextual information for a specific entity.
+ */
+export type BasicSyncEntityCommonTypeSynchronizerEntitySourceContextLoader = (entity: SyncEntityCommonTypeIdPair) => Promise<BasicSyncEntityCommonTypeSynchronizerEntitySourceContextLoaderResult>;
+export interface BasicSyncEntityCommonTypeSynchronizerConfig {
+    readonly commonType: SyncEntityCommonType;
+    /**
+     * If true, the sources are considered to be dynamic and will be reloaded/configured each time the synchronizer is called.
+     *
+     * Defaults to false.
+     */
+    readonly dynamicSources?: boolean;
+    /**
+     * All sources for this entity type for this synchronizer.
+     */
+    readonly sources: BasicSyncEntityCommonTypeSynchronizerSource[];
+    /**
+     * Loads source contextual information for any source that requires context.
+     */
+    readonly entitySourceContextLoader: BasicSyncEntityCommonTypeSynchronizerEntitySourceContextLoader;
+}
+export declare function basicSyncEntityCommonTypeSynchronizerInstanceFactory(config: BasicSyncEntityCommonTypeSynchronizerConfig): BasicSyncEntityCommonTypeSynchronizer;

package/src/lib/service/sync/sync.entity.synchronizer.d.ts

@@ -0,0 +1,128 @@
+import { SyncEntity, SyncEntityCommonType, SyncEntityCommonTypeIdPair, SyncEntityCommonTypeIdPairFactoryInput } from './sync.entity';
+import { Maybe } from '@dereekb/util';
+/**
+ * The context type of source for an entity.
+ *
+ * - Global: The source is available to all contexts. Example: Configured API for the server.
+ * - Context: The source is only available to a specific context. Example: Configured per-user OAuth client for a specific user.
+ */
+export type SyncEntityCommonTypeSynchronizerSourceContextType = 'global' | 'context';
+/**
+ * The flow type of source for an entity. These are used to determine the order of synchronization.
+ *
+ * - Primary: The general/primary source of truth for an entity. There should typically only be one primary source.
+ * When a primary source returns deleted, then all other sources will be notified for deletion.
+ *
+ * - Secondary: A secondary source for the entity that information can be pulled from and may be used to update the primary source.
+ * When a secondary source returns deleted, then the synchronization will be restarted so the primary source(s) will be synchronized again to confirm the deletion.
+ *
+ * - Replica: A replica of the primary source for the entity that is never used to update other sources.
+ * - Unset: The flow type is not set. This is only used when a source is not configured properly and will be ignored.
+ */
+export type SyncEntityCommonTypeSynchronizerSourceFlowType = 'primary' | 'secondary' | 'replica' | 'unset';
+/**
+ * The base synchronizer for entities.
+ */
+export interface SyncEntitySynchronizer {
+    /**
+     * List of common types that can be synchronized by this synchronizer.
+     */
+    readonly commonTypes: SyncEntityCommonType[];
+    /**
+     * Returns the synchronizer for the given common type.
+     *
+     * Throws an error if the common type is not registered.
+     *
+     * @param input The common type to synchronize.
+     * @returns The synchronizer for the common type.
+     */
+    commonTypeSynchronizer(input: SyncEntityCommonType): SyncEntityCommonTypeSynchronizer;
+    /**
+     * Creates a new synchronizer instance for the input entity.
+     *
+     * Throws an error if the common type is not registered.
+     *
+     * @param input The common type and id of the entity to synchronize.
+     * @returns The synchronizer instance for the entity.
+     */
+    synchronizeInstance(input: SyncEntityCommonTypeSynchronizerInstanceInput): Promise<SyncEntityCommonTypeSynchronizerInstance>;
+}
+export interface SyncEntitySynchronizerConfig {
+    readonly commonTypeSynchronizers: SyncEntityCommonTypeSynchronizer[];
+}
+export declare function syncEntitySynchronizer(config: SyncEntitySynchronizerConfig): SyncEntitySynchronizer;
+export type SyncEntityCommonTypeSynchronizerInstanceInput = SyncEntityCommonTypeIdPairFactoryInput;
+export type SyncEntityCommonTypeSynchronizerInstanceFunction = (input: SyncEntityCommonTypeSynchronizerInstanceInput) => Promise<SyncEntityCommonTypeSynchronizerInstance>;
+/**
+ * Used for creating a new synchronization strategy for entities of a specific common type.
+ */
+export interface SyncEntityCommonTypeSynchronizer {
+    /**
+     * The common type for the entity.
+     */
+    readonly commonType: SyncEntityCommonType;
+    /**
+     * Creates a new synchronizer for the entity.
+     *
+     * @param input The common type and id of the entity to synchronize.
+     * @returns The synchronizer for the entity.
+     */
+    readonly synchronizeInstance: SyncEntityCommonTypeSynchronizerInstanceFunction;
+}
+/**
+ * The result of synchronizing an entity.
+ */
+export interface SyncEntityCommonTypeSynchronizationResult {
+    readonly targetPair: SyncEntityCommonTypeIdPair;
+    readonly entitiesSynchronized: SyncEntityCommonTypeSynchronizationEntityResult[];
+}
+/**
+ * The result of a synchronization. This return type/instance has different implications for different sources of different types.
+ *
+ * - nochange: The entity was unchanged.
+ * - synchronized: The entity was synchronized.
+ * - deleted: The entity was deleted or is already deleted. If this is a primary source then the entity will be deleted from all other sources. If this
+ * is a secondary source then the synchronization will be restarted so the primary source(s) will be resynchronized again.
+ * - failed: The entity was not synchronized due to a failure that was controlled. Unless this is a primary source, should not cancel the synchronization of other sources.
+ * - error: An unexpected error occurred during synchronization.
+ */
+export type SyncEntityCommonTypeSynchronizationEntityResultType = 'nochange' | 'synchronized' | 'deleted' | 'failed' | 'error';
+/**
+ * Specific entity synchronization information within a SyncEntityCommonTypeSynchronizationResult.
+ */
+export interface SyncEntityCommonTypeSynchronizationEntityResult {
+    /**
+     * The entity that was synchronized.
+     *
+     * For results with the "error" result type, the actual id may not be provided or accurate.
+     */
+    readonly entity: SyncEntity;
+    /**
+     * The type of result.
+     */
+    readonly type: SyncEntityCommonTypeSynchronizationEntityResultType;
+    /**
+     * The error that occurred during synchronization, if one occured.
+     */
+    readonly error?: Maybe<unknown>;
+}
+export interface SyncEntityCommonTypeSynchronizerFunctionContext {
+}
+/**
+ * Performs the synchronization process for the given entity.
+ *
+ * @returns A promise that resolves when the synchronization is complete.
+ */
+export type SyncEntityCommonTypeSynchronizerFunction = (context?: Maybe<SyncEntityCommonTypeSynchronizerFunctionContext>) => Promise<SyncEntityCommonTypeSynchronizationResult>;
+/**
+ * A concrete instance that refernces a specific entity to synchronize.
+ */
+export interface SyncEntityCommonTypeSynchronizerInstance {
+    readonly entityPair: SyncEntityCommonTypeIdPair;
+    /**
+     * Performs the synchronization process for the given entity.
+     *
+     * @returns A promise that resolves when the synchronization is complete.
+     */
+    readonly synchronize: SyncEntityCommonTypeSynchronizerFunction;
+}

package/src/lib/service/sync/sync.error.d.ts

@@ -0,0 +1,31 @@
+import { BaseError } from 'make-error';
+import { SyncEntityCommonType, SyncEntityCommonTypeIdPair } from './sync.entity';
+/**
+ * Error thrown when the common type is not known/registered.
+ */
+export declare class UnregisteredSyncEntityCommonTypeError extends BaseError {
+    readonly commonType: SyncEntityCommonType;
+    constructor(commonType: SyncEntityCommonType);
+}
+/**
+ * Error thrown when no primary sync source is found for an entity.
+ */
+export declare class NoPrimarySyncSourceError extends BaseError {
+    readonly entity: SyncEntityCommonTypeIdPair;
+    constructor(entity: SyncEntityCommonTypeIdPair);
+}
+/**
+ * Error thrown when multiple primary sync sources are found for an entity.
+ */
+export declare class MultiplePrimarySyncSourceError extends BaseError {
+    readonly entity: SyncEntityCommonTypeIdPair;
+    constructor(entity: SyncEntityCommonTypeIdPair);
+}
+/**
+ * Error thrown when a synchronization fails for an entity.
+ */
+export declare class SynchronizationFailedError extends BaseError {
+    readonly entity: SyncEntityCommonTypeIdPair;
+    readonly error: unknown;
+    constructor(entity: SyncEntityCommonTypeIdPair, error: unknown);
+}

package/src/lib/service/sync/sync.service.d.ts

@@ -0,0 +1,3 @@
+export interface SyncSystem {
+    synchronize(): Promise<void>;
+}

package/src/lib/service/sync/sync.source.d.ts

@@ -0,0 +1,34 @@
+/**
+ * English name for a SyncSource.
+ *
+ * Is not used as a key.
+ */
+export type SyncSourceName = string;
+/**
+ * A unique identifier for a SyncSource.
+ */
+export type SyncSourceId = string;
+/**
+ * Information for a SyncSource.
+ */
+export interface SyncSourceInfo {
+    readonly id: SyncSourceId;
+    readonly name: SyncSourceName;
+}
+/**
+ * A generic API/server that contains entities.
+ */
+export interface SyncSource {
+    readonly info: SyncSourceInfo;
+}
+/**
+ * Contextual information for a SyncSource.
+ */
+export interface SyncSourceClientContext {
+}
+/**
+ * Details for a SyncSource for a specific context, such as an OAuth user/client.
+ */
+export interface SyncSourceClientDetails<T = unknown> {
+    readonly details: T;
+}