@jpmorganchase/mosaic-types 0.1.0-beta.3 → 0.1.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @jpmorganchase/mosaic-types
 
+## 0.1.0-beta.5
+
+### Patch Changes
+
+- 61a246c: This releases add support for generate / build and serve snapshots
+
+## 0.1.0-beta.4
+
+### Patch Changes
+
+- bd285df: added dist to package.json
+
 ## 0.1.0-beta.3
 
 ### Patch Changes

package/dist/IFileAccess.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="node" />
+import type { DirectoryJSON, IRealpathOptions, IMkdirOptions, IReaddirOptions, TData, TMode } from 'memfs/lib/volume';
+import type { TDataOut } from 'memfs/lib/encoding';
+import type Dirent from 'memfs/lib/Dirent';
+import type Stats from 'memfs/lib/Stats';
+import type { TStatNumber } from 'memfs/lib/Stats';
+import type { IStatOptions } from 'memfs/lib/volume';
+import type { PathLike, symlink } from 'fs';
+import type { Page } from './Page';
+import type { Options, Pattern, Entry } from 'fast-glob';
+/**
+ * This is the core underlying filesystem, which directly interfaces with a memfs Volume to mutate the filesystem
+ */
+export interface IFileAccess {
+    glob(pattern: Pattern, options?: Omit<Options, 'absolute' | 'fs'>): Promise<string[] | Entry[]>;
+    mkdir(dir: PathLike, options?: TMode | IMkdirOptions): Promise<void>;
+    readdir(dir: PathLike, options?: string | IReaddirOptions): Promise<TDataOut[] | Dirent[]>;
+    readFile(file: PathLike): Promise<TDataOut>;
+    realpath(target: string, options?: string | IRealpathOptions): Promise<TDataOut>;
+    stat(file: PathLike, options?: IStatOptions): Promise<Stats<TStatNumber>>;
+    unlink(target: PathLike): Promise<void>;
+    symlink(target: PathLike, alias: PathLike, type?: symlink.Type): Promise<void>;
+    writeFile(file: PathLike, data: TData): Promise<void>;
+    toJSON(): DirectoryJSON;
+    fromJSON(json: DirectoryJSON): void;
+    exists(file: PathLike): Promise<boolean>;
+    $$reset(): void;
+    $$freeze(): void;
+    readonly $$frozen: boolean;
+    $$unfreeze(): void;
+    $$clearCache(): void;
+    $$symlinksFromJSON(page: {
+        [key: string]: {
+            target: string;
+            type: string;
+        }[];
+    }): Promise<void>;
+    symlinksToJSON(): {
+        [key: string]: {
+            target: string;
+            type: string;
+        }[];
+    };
+    $$addReadFileHook(hook: (result: Page, filepath: PathLike) => Promise<Page>): void;
+}

package/dist/Meta.d.ts

@@ -0,0 +1,5 @@
+export declare type Meta<AdditionalProps> = {
+    title?: string;
+    route: string;
+    lastModified: Date;
+} & Record<string, unknown> & AdditionalProps;

package/dist/MutableData.d.ts

@@ -0,0 +1,74 @@
+export interface Aliases {
+    [key: string]: Set<string>;
+}
+export interface FSRef {
+    $$path?: string | string[];
+    $$value?: string;
+}
+export interface GlobalRefs {
+    [key: string]: FSRef;
+}
+export interface ScopedRefs {
+    [key: string]: FSRef;
+}
+export interface BaseData {
+    refs?: ScopedRefs | [];
+    globalRefs?: GlobalRefs | [];
+    aliases?: Aliases | [];
+}
+export declare type MutableData<T = {}> = ImmutableData<T> & {
+    /**
+     * Set arbitrary data onto the config object. This value will persist across plugins and
+     * also be sent to the parent process when it executes plugins there as well.
+     * Values can be retrieved from `data`.
+     * This data is one-way, it can only be set/mutated in the child process lifecycle stages
+     * This will be reset everytime the relevant source receives new pages
+     * @param data Data to MERGE into the existing blob
+     */
+    setData(data: Partial<T>, overwrite?: boolean): void;
+    /**
+     * Helper function for declaring new aliases that will be applied by the AliasPlugin.
+     * Values can be retrieved from `data.aliases`
+     * This will be reset everytime the relevant source receives new pages
+     * @param fullPath The file/fullPath the alias will point to
+     * @param aliases Array of aliases to use when pointing to this page
+     */
+    setAliases(targetPath: string, aliases: string[]): void;
+    /**
+     * Helper function for declaring new tags (which are basically aliases to /.tags) that will be applied by the AliasPlugin.
+     * Values can be retrieved from `data.aliases`
+     * This will be reset everytime the relevant source receives new pages
+     * @param fullPath The file/fullPath the alias will point to
+     * @param tags Array of tag names to use when pointing to this page
+     */
+    setTags(targetPath: string, tags: string[]): void;
+    /**
+     * Helper function for declaring new refs that will be applied by the RefPlugin
+     * This will be reset everytime the relevant source receives new pages
+     * Values can be retrieved from `data.refs`
+     * @param targetPath The file/fullPath to write the ref to
+     * @param targetPropPath The path to the property where the ref will be applied
+     * @param refValue The value of the ref (can be a wildcard)
+     */
+    setRef(targetFilepath: string, targetPropPath: string | string[], refValue: string): void;
+    /**
+     * Same as `setRef`, but do not pre-resolve this ref - wait until the file is read and use the global filesystem for it
+     * @param targetPath The file/fullPath to write the ref to
+     * @param targetPropPath The path to the property where the ref will be applied
+     * @param refValue The value of the ref (can be a wildcard)
+     */
+    setGlobalRef(targetFilepath: string, targetPropPath: string | string[], refValue: string): void;
+    /**
+     * This object, but without the mutation methods like `setAliases`, `setData` etc
+     */
+    asReadOnly(): ImmutableData<T>;
+};
+export declare type ImmutableData<T = {}> = {
+    readonly data: Readonly<T & {
+        readonly refs: string[];
+        readonly aliases: Set<{
+            $$path: string[];
+            $$value: string;
+        }>;
+    }>;
+};

package/dist/Page.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `Page` is a type, which at a minimum has a `fullPath`, but can also contain metadata and `content`
+ */
+export declare type Page<AdditionalProps = {}> = {
+    fullPath: string;
+    title?: string;
+    /**
+     * Friendly fullPaths are the shortest possible paths that will point to a page.
+     * They are useful for creating more user-friendly links on pages, rather than using a full filesystem path.
+     * They originally start as the same as `fullPath`, but can be modified by plugins whenever they make a change to how a page resolves.
+     * e.g. The `PagesWithoutFileExtPlugin` modifies the friendly fullPath after it creates aliases for every page (to allow
+     * them to be referenced without a file extension). Another example would be a plugin that allows `/index` to be
+     * automatically added if a fullPath points to a directory -- the `route` could then be modified by that
+     * plugin to remove `/index`
+     */
+    route?: string;
+    lastModified?: Date;
+    type?: string;
+    content?: string;
+} & Record<string, unknown> & AdditionalProps;

package/dist/Plugin.d.ts

@@ -0,0 +1,91 @@
+import type { Page } from './Page';
+import type { MutableData } from './MutableData';
+import type { PluginModuleDefinition } from './PluginModuleDefinition';
+import type { ImmutableData } from './MutableData';
+import type { IUnionVolume, IVolumeImmutable, IVolumeMutable, IVolumePartiallyMutable } from './Volume';
+import type { Serialiser } from './Serialiser';
+export declare type LoadedPlugin = Partial<Plugin> & PluginModuleDefinition;
+/**
+ * Plugins are lifecycle-based hooks that are called on every source at different stages.
+ * Consumers will never need to invoke a lifecycle method; but for technical clarity - when a lifecycle method is called,
+ * it will trigger `pluginRunner` which executes it on every source automatically.
+ */
+export declare type Plugin<ConfigData = {}, PluginOptions = {}, GlobalConfigData = ConfigData> = {
+    /**
+     * Plugin lifecycle method that triggers inside child processes.
+     * The first lifecycle hook to trigger after receiving pages from a source. The pages can safely be mutated and will be reflected in the final
+     * filesystem that gets generated.
+     * @param pages Array of pages from the source
+     * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
+     * @param param.config A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin
+     * @param options The options passed in when declaring the plugin
+     * @returns {Promise<Page[]>} Must re-return an array of `Page` objects, modified or not
+     */
+    $afterSource?(pages: Page[], {}: {
+        serialiser: Serialiser;
+        config: MutableData<ConfigData>;
+        pageExtensions: string[];
+        ignorePages: string[];
+    }, options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions): Promise<Page[]>;
+    /**
+     * Plugin lifecycle method that triggers inside child processes.
+     * Calls after a filesystem has been built up from the source pages.
+     * @param mutableFilesystem Mutable virtual filesystem instance with all of this source's pages inside (and symlinks applied)
+     * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
+     * @param param.config A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin
+     * @param options The options passed in when declaring the plugin
+     * @returns {void} No return expected
+     */
+    $beforeSend?(mutableFilesystem: IVolumePartiallyMutable, {}: {
+        serialiser: Serialiser;
+        pageExtensions: string[];
+        ignorePages: string[];
+        config: MutableData<ConfigData>;
+    }, options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions): Promise<void>;
+    /**
+     * Plugin lifecycle method that triggers inside the main process.
+     * Calls after the filesystem and symlinks have been reconstructed due to a change to the current source. This happens in the main thread.
+     * Pages will NOT be cached when read at this stage, to allow for reading content and writing a new copy of it without the cached version taking effect.
+     * This method is safe to use with lazy loading, as the filesystem should return the full page when read.
+     * NOTE: Plugin methods that trigger inside the parent process should be async and highly optimised to avoid holding up the main thread.
+     * You should also be mindful of race conditions when reading / writing to the global filesystem from this method - as other plugins may
+     * also have a read copy of the same file and it could end up out of sync.
+     * @param mutableFilesystem Mutable filesystem instance with all of this source's pages inside (and symlinks re-applied)
+     * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
+     * @param param.config An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. Shared only with this source.
+     * @param param.globalConfig An immutable object for reading data from other lifecycle phases of all plugins. Shared across all sources.
+     * @param param.sharedFilesystem Mutable filesystem instance independent of any sources. Useful for global pages, like sitemaps
+     * @param param.globalFilesystem Immutable union filesystem instance with all source's pages (and symlinks applied)
+     * @param options The options passed in when declaring the plugin
+     * @returns {void} No return expected
+     */
+    afterUpdate?(mutableFilesystem: IVolumePartiallyMutable, {}: {
+        serialiser: Serialiser;
+        config: ImmutableData<ConfigData>;
+        globalFilesystem: IUnionVolume;
+        sharedFilesystem: IVolumeMutable;
+        globalConfig: ImmutableData<GlobalConfigData>;
+        pageExtensions: string[];
+        ignorePages: string[];
+    }, options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions): Promise<void>;
+    /**
+     * Plugin lifecycle method that triggers inside the main process everytime ANY source emits new pages.
+     * This method should return a boolean that will indicate if this source should clear page caches.
+     * This method calls whenever another source (not this one) has changed.
+     * Returning `undefined`, false or no value, will result in the cache to be retained
+     * @param updatedSourceFilesystem Immutable filesystem for the source that changed
+     * @param param.config An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin
+     * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
+     * @param param.globalFilesystem Immutable union filesystem instance with all source's pages (and symlinks applied)
+     * @param options The options passed in when declaring the plugin
+     * @returns {Promise<boolean>} A boolean indicating whether to clear the cache for this source
+     */
+    shouldClearCache?(updatedSourceFilesystem: IVolumeImmutable, {}: {
+        serialiser: Serialiser;
+        config: ImmutableData<ConfigData>;
+        globalFilesystem: IUnionVolume;
+        pageExtensions: string[];
+        ignorePages: string[];
+    }, options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions): Promise<boolean>;
+};
+export declare type LifecycleMethod = keyof Plugin;

package/dist/PluginModuleDefinition.d.ts

@@ -0,0 +1,19 @@
+export interface PluginModuleDefinition {
+    /**
+     * Options to pass to the plugin lifecycle methods.
+     */
+    options: Record<string, unknown>;
+    /**
+     * The importance of this plugin. This highest number plugin will be run first
+     */
+    priority?: number;
+    /**
+     * Exclude this plugin when running `mosaic build`
+     */
+    runTimeOnly?: boolean;
+    /**
+     * Path to the JS file for this plugin (can either export a `default` module with lifecycle methods,
+     * or export the methods individually)
+     */
+    modulePath: string;
+}

package/dist/PullDocsConfig.d.ts

@@ -0,0 +1,10 @@
+import type { PluginModuleDefinition } from './PluginModuleDefinition';
+import type { SerialiserModuleDefinition } from './SerialiserModuleDefinition';
+import type { SourceModuleDefinition } from './SourceModuleDefinition';
+export interface PullDocsConfig {
+    pageExtensions: Array<string>;
+    ignorePages?: Array<string>;
+    serialisers: Array<SerialiserModuleDefinition>;
+    plugins: Array<PluginModuleDefinition>;
+    sources: Array<SourceModuleDefinition>;
+}

package/dist/Serialiser.d.ts

@@ -0,0 +1,26 @@
+import type { TDataOut } from 'memfs/lib/encoding';
+import type { Page } from './Page';
+import type { SerialiserModuleDefinition } from './SerialiserModuleDefinition';
+/**
+ * Serialisers are a form of plugin that tells PullDocs how to turn a file from/to a storable form for the filesystem
+ * or a `Page` object.
+ * For technical clarity - when a parser method is called, it will trigger `parserRunner` which checks the `fullPath` against
+ * the `test` option that was passed in the PullDocs config file, to find a suitable parser.
+ */
+export declare type Serialiser = {
+    /**
+     * Method to turn a raw page (e.g. an MDX file) into a `Page` object
+     * @param fullPath Route on virtual disk (should be full fullPath, not an alias)
+     * @param page Page in string or buffer form (i.e. an MDX page with frontmatter or a JSON file as a string)
+     * @returns Page object in the `Page` format
+     */
+    deserialise: (fullPath: string, page: TDataOut) => Promise<Page>;
+    /**
+     * Method to load a raw page from disk (e.g. an MDX file) and return into a `Page` object
+     * @param fullPath Route on virtual disk (should be full fullPath, not an alias)
+     * @param page Page in `Page` form
+     * @returns Page content
+     */
+    serialise: (fullPath: string, page: Page) => Promise<TDataOut>;
+};
+export declare type LoadedSerialiser = Serialiser & SerialiserModuleDefinition;

package/dist/SerialiserModuleDefinition.d.ts

@@ -0,0 +1,4 @@
+import type { PluginModuleDefinition } from './PluginModuleDefinition';
+export declare type SerialiserModuleDefinition = PluginModuleDefinition & {
+    filter: RegExp;
+};

package/dist/Source.d.ts

@@ -0,0 +1,9 @@
+import type { Observable } from 'rxjs';
+import type { Serialiser } from './Serialiser';
+import type { Page } from './Page';
+export declare type Source<Options = {}> = {
+    create(options: Options, { serialiser, pageExtensions }: {
+        pageExtensions: string[];
+        serialiser: Serialiser;
+    }): Observable<Page[]>;
+};

package/dist/SourceModuleDefinition.d.ts

@@ -0,0 +1,5 @@
+import type { PluginModuleDefinition } from './PluginModuleDefinition';
+export declare type SourceModuleDefinition = PluginModuleDefinition & {
+    namespace: string;
+    cache?: boolean;
+};

package/dist/Volume.d.ts

@@ -0,0 +1,130 @@
+/// <reference types="node" />
+import type { DirectoryJSON, IRealpathOptions, IMkdirOptions, IReaddirOptions, TData, TMode } from 'memfs/lib/volume';
+import type { TDataOut } from 'memfs/lib/encoding';
+import type Dirent from 'memfs/lib/Dirent';
+import type Stats from 'memfs/lib/Stats';
+import type { TStatNumber } from 'memfs/lib/Stats';
+import type { IStatOptions } from 'memfs/lib/volume';
+import type { PathLike, symlink } from 'fs';
+import type { Options, Pattern, Entry } from 'fast-glob';
+/**
+ * Volumes are lightweight decorators which wrap `FileAccess` and limit access to the underlying API for different use-cases
+ * Examples include disallowing mutation or allowing underlying functions like resetting
+ */
+export interface IVolume {
+    namespace: string;
+    reset?(): void;
+    toJSON(): DirectoryJSON;
+    symlinksToJSON(): {
+        [key: string]: {
+            target: string;
+            type: string;
+        }[];
+    };
+    fromJSON?(json: DirectoryJSON): void;
+    promises: {
+        exists(file: PathLike): Promise<boolean>;
+        glob(pattern: Pattern, options?: Options): Promise<string[] | Entry[]>;
+        mkdir(dir: PathLike, options?: TMode | IMkdirOptions): Promise<void>;
+        readdir(dir: PathLike, options?: string | IReaddirOptions): Promise<TDataOut[] | Dirent[]>;
+        readFile(file: PathLike): Promise<TDataOut>;
+        realpath(target: string, options?: string | IRealpathOptions): Promise<TDataOut>;
+        stat(file: PathLike, options?: IStatOptions): Promise<Stats<TStatNumber>>;
+        symlink(target: PathLike, alias: PathLike, type?: symlink.Type): Promise<void>;
+        unlink(target: PathLike): Promise<void>;
+        writeFile(file: PathLike, data: TData): Promise<void>;
+    };
+}
+export interface IVolumePartiallyMutable extends Omit<IVolume, 'reset' | 'fromJSON'> {
+    /**
+     * Functions that will be called after a page is read from the filesystem for the first time (since last cache clear).
+     * The value returned from this hook will *replace* the contents of the read file.
+     * @param hook Any function that invokes an `afterRead` plugin
+     * @returns Promise<Page>
+     */
+    __internal_do_not_use_addReadFileHook(hook: (filepath: PathLike, fileData: TDataOut) => Promise<TDataOut>): void;
+}
+export interface IUnionVolume extends Omit<IVolumeImmutable, 'promises'> {
+    promises: Pick<IVolumeImmutable, 'promises'> & {
+        /**
+         * Reads a file
+         * @param file Path
+         * @returns Promise<TDataOut>
+         */
+        readFile(file: PathLike): Promise<TDataOut>;
+        readFile(file: PathLike, options?: {
+            includeConflicts?: false;
+        }): Promise<TDataOut>;
+        /**
+         * Reads 1 or more files (if multiple files exist at the same location within the union filesystem)
+         * @param file Path
+         * @param options.includeConflicts If multiple files exist at the same location in the filesystem, return them all as an array
+         * @returns Promise<TDataOut[]>
+         */
+        readFile(file: PathLike, options: {
+            includeConflicts: true;
+        }): Promise<TDataOut[]>;
+    };
+    /**
+     * Scopes a filesystem to specific namespaces
+     * @param {string[]} namespaces Array of namespaces to limit this filesystem to
+     * @returns A new immutable union filesystem
+     */
+    scope(namespaces: string[]): IUnionVolume;
+}
+export interface IVolumeMutable extends IVolume {
+    /**
+     * Functions that will be called after a page is read from the filesystem for the first time (since last cache clear).
+     * The value returned from this hook will *replace* the contents of the read file.
+     * @param hook Any function that invokes an `afterRead` plugin
+     * @returns Promise<Page>
+     */
+    __internal_do_not_use_addReadFileHook(hook: (filepath: PathLike, fileData: TDataOut) => Promise<TDataOut>): void;
+    /**
+     * Restricted filesystems can be written to, but cannot be frozen, updated or reset
+     */
+    asRestricted(): IVolumePartiallyMutable;
+    /**
+     * ReadOnly filesystems cannot be mutated in any way, including freezing, updating or reseting
+     */
+    asReadOnly(): IVolumeImmutable;
+    /**
+     * Clears the filesystem's internal page cache - used when the cache may be outdated due to a source emiting new data or a dependency changing.
+     */
+    clearCache(): void;
+    /**
+     * Re-enables mutations on the underlying `FileAccess`.
+     */
+    unfreeze(): void;
+    /**
+     * Freezes an object, preventing all mutations on the underlying `FileAccess` object
+     * Freezing a filesystem indicates that the mutation period has ended and the file system can no longer be modified.
+     * When a filesystem is unfrozen, it is considered to be in flux, so may change as more plugins are called.
+     * When a filesystem is frozen, it is considered to be stable and ready to begin serving finalised versions of files.
+     */
+    freeze(): void;
+    /**
+     * Is this filesystem frozen/mutable?
+     * @returns {boolean}
+     */
+    readonly frozen: boolean;
+    /**
+     * Appends content to the filesystem
+     * @param json A JSON blob in the form of {[fullPath]: "{fullPath: '', content: ''}"}
+     */
+    fromJSON(json: DirectoryJSON): void;
+    symlinksFromJSON(json: {
+        [key: string]: {
+            target: string;
+            type: string;
+        }[];
+    }): Promise<void>;
+    /**
+     * Completely resets the filesystem.
+     * This includes clearing page cache, erasing filesystem data, clearing symlinks etc
+     */
+    reset(): void;
+}
+export interface IVolumeImmutable extends Omit<IVolumePartiallyMutable, 'fromJSON' | 'reset' | 'promises' | '__internal_do_not_use_addReadFileHook'> {
+    promises: Omit<IVolume['promises'], 'writeFile' | 'symlink' | 'mkdir' | 'unlink' | 'rmdir' | 'rm' | 'rename'>;
+}

package/dist/WorkerData.d.ts

@@ -0,0 +1,15 @@
+import type { SerialiserModuleDefinition } from './SerialiserModuleDefinition';
+import type { PluginModuleDefinition } from './PluginModuleDefinition';
+import type { SourceModuleDefinition } from './SourceModuleDefinition';
+export declare type WorkerData<Options = {}> = {
+    options: Options & Pick<PluginModuleDefinition, 'options'> & Pick<SourceModuleDefinition, 'options'> & {
+        pageExtensions: string[];
+    };
+    name: string;
+    namespace: string;
+    pageExtensions: string[];
+    ignorePages: string[];
+    plugins: PluginModuleDefinition[];
+    serialisers: SerialiserModuleDefinition[];
+    modulePath: string;
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './IFileAccess';
+export * from './Meta';
+export * from './MutableData';
+export * from './Page';
+export * from './Plugin';
+export * from './PluginModuleDefinition';
+export * from './PullDocsConfig';
+export * from './Serialiser';
+export * from './SerialiserModuleDefinition';
+export * from './Source';
+export * from './SourceModuleDefinition';
+export * from './Volume';
+export * from './WorkerData';

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@jpmorganchase/mosaic-types",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "author": "",
-  "description": "",
+  "description": "Mosaic BitBucket source for core file system",
   "license": "Apache-2.0",
-  "types": "./dist/**",
+  "types": "./dist/index.d.ts",
   "engines": {
     "node": ">= 12.0.0"
   },
@@ -12,6 +12,9 @@
     "type": "git",
     "url": "git@github.com:jpmorganchase/mosaic.git"
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "clean": "rm -fr dist"
@@ -19,4 +22,4 @@
   "devDependencies": {
     "rxjs": "^7.5.5"
   }
-}
+}

package/.turbo/turbo-build.log

@@ -1,2 +0,0 @@
-@jpmorganchase/mosaic-types:build: cache hit, replaying output 9084cbc397462f27
-@jpmorganchase/mosaic-types:build: $ tsc

package/.turbo/turbo-clean.log

@@ -1,2 +0,0 @@
-@jpmorganchase/mosaic-types:clean: cache hit, replaying output cf8c2b7775336107
-@jpmorganchase/mosaic-types:clean: $ rm -fr dist

package/src/IFileAccess.ts

@@ -1,42 +0,0 @@
-import type {
-  DirectoryJSON,
-  IRealpathOptions,
-  IMkdirOptions,
-  IReaddirOptions,
-  TData,
-  TMode
-} from 'memfs/lib/volume';
-import type { TDataOut } from 'memfs/lib/encoding';
-import type Dirent from 'memfs/lib/Dirent';
-import type Stats from 'memfs/lib/Stats';
-import type { TStatNumber } from 'memfs/lib/Stats';
-import type { IStatOptions } from 'memfs/lib/volume';
-import type { PathLike, symlink } from 'fs';
-import type Page from './Page';
-import type { Options, Pattern, Entry } from 'fast-glob';
-
-/**
- * This is the core underlying filesystem, which directly interfaces with a memfs Volume to mutate the filesystem
- */
-export default interface IFileAccess {
-  glob(pattern: Pattern, options?: Omit<Options, 'absolute' | 'fs'>): Promise<string[] | Entry[]>;
-  mkdir(dir: PathLike, options?: TMode | IMkdirOptions): Promise<void>;
-  readdir(dir: PathLike, options?: string | IReaddirOptions): Promise<TDataOut[] | Dirent[]>;
-  readFile(file: PathLike): Promise<TDataOut>;
-  realpath(target: string, options?: string | IRealpathOptions): Promise<TDataOut>;
-  stat(file: PathLike, options?: IStatOptions): Promise<Stats<TStatNumber>>;
-  unlink(target: PathLike): Promise<void>;
-  symlink(target: PathLike, alias: PathLike, type?: symlink.Type): Promise<void>;
-  writeFile(file: PathLike, data: TData): Promise<void>;
-  toJSON(): DirectoryJSON;
-  fromJSON(json: DirectoryJSON): void;
-  exists(file: PathLike): Promise<boolean>;
-  $$reset(): void;
-  $$freeze(): void;
-  get $$frozen(): boolean;
-  $$unfreeze(): void;
-  $$clearCache(): void;
-  $$symlinksFromJSON(page: { [key: string]: { target: string; type: string }[] }): Promise<void>;
-  symlinksToJSON(): { [key: string]: { target: string; type: string }[] };
-  $$addReadFileHook(hook: (result: Page, filepath: PathLike) => Promise<Page>): void;
-}

package/src/Meta.ts

@@ -1,9 +0,0 @@
-type Meta<AdditionalProps> = {
-  title?: string;
-  // `route` is a fullPath that points to the page, similar to how `page`.`fullPath` does - but this may be an alias instead,
-  // so it can be used for presenting more aesthetic URLs etc when used as a site href
-  route: string;
-  lastModified: Date;
-} & Record<string, unknown> &
-  AdditionalProps;
-export default Meta;

package/src/MutableData.ts

@@ -1,55 +0,0 @@
-type MutableData<T = {}> = ImmutableData<T> & {
-  /**
-   * Set arbitrary data onto the config object. This value will persist across plugins and
-   * also be sent to the parent process when it executes plugins there as well.
-   * Values can be retrieved from `data`.
-   * This data is one-way, it can only be set/mutated in the child process lifecycle stages
-   * This will be reset everytime the relevant source receives new pages
-   * @param data Data to MERGE into the existing blob
-   */
-  setData(data: Partial<T>, overwrite?: boolean): void;
-  /**
-   * Helper function for declaring new aliases that will be applied by the AliasPlugin.
-   * Values can be retrieved from `data.aliases`
-   * This will be reset everytime the relevant source receives new pages
-   * @param fullPath The file/fullPath the alias will point to
-   * @param aliases Array of aliases to use when pointing to this page
-   */
-  setAliases(targetPath: string, aliases: string[]): void;
-  /**
-   * Helper function for declaring new tags (which are basically aliases to /.tags) that will be applied by the AliasPlugin.
-   * Values can be retrieved from `data.aliases`
-   * This will be reset everytime the relevant source receives new pages
-   * @param fullPath The file/fullPath the alias will point to
-   * @param tags Array of tag names to use when pointing to this page
-   */
-  setTags(targetPath: string, tags: string[]): void;
-  /**
-   * Helper function for declaring new refs that will be applied by the RefPlugin
-   * This will be reset everytime the relevant source receives new pages
-   * Values can be retrieved from `data.refs`
-   * @param targetPath The file/fullPath to write the ref to
-   * @param targetPropPath The path to the property where the ref will be applied
-   * @param refValue The value of the ref (can be a wildcard)
-   */
-  setRef(targetFilepath: string, targetPropPath: string | string[], refValue: string): void;
-  /**
-   * Same as `setRef`, but do not pre-resolve this ref - wait until the file is read and use the global filesystem for it
-   * @param targetPath The file/fullPath to write the ref to
-   * @param targetPropPath The path to the property where the ref will be applied
-   * @param refValue The value of the ref (can be a wildcard)
-   */
-  setGlobalRef(targetFilepath: string, targetPropPath: string | string[], refValue: string): void;
-  /**
-   * This object, but without the mutation methods like `setAliases`, `setData` etc
-   */
-  asReadOnly(): ImmutableData<T>;
-};
-
-export type ImmutableData<T = {}> = {
-  readonly data: Readonly<
-    T & { readonly refs: string[]; readonly aliases: Set<{ $$path: string[]; $$value: string }> }
-  >;
-};
-
-export default MutableData;

package/src/Page.ts

@@ -1,23 +0,0 @@
-/**
- * `Page` is a type, which at a minimum has a `fullPath`, but can also contain metadata and `content`
- */
-type Page<AdditionalProps = {}> = {
-  fullPath: string;
-  title?: string;
-  /**
-   * Friendly fullPaths are the shortest possible paths that will point to a page.
-   * They are useful for creating more user-friendly links on pages, rather than using a full filesystem path.
-   * They originally start as the same as `fullPath`, but can be modified by plugins whenever they make a change to how a page resolves.
-   * e.g. The `PagesWithoutFileExtPlugin` modifies the friendly fullPath after it creates aliases for every page (to allow
-   * them to be referenced without a file extension). Another example would be a plugin that allows `/index` to be
-   * automatically added if a fullPath points to a directory -- the `route` could then be modified by that
-   * plugin to remove `/index`
-   */
-  route?: string;
-  lastModified?: Date;
-  type?: string;
-  content?: string;
-} & Record<string, unknown> &
-  AdditionalProps;
-
-export default Page;

package/src/Plugin.ts

@@ -1,112 +0,0 @@
-import type Page from './Page';
-import type MutableData from './MutableData';
-import type PluginModuleDefinition from './PluginModuleDefinition';
-import type { ImmutableData } from './MutableData';
-import type { IUnionVolume, IVolumeImmutable, IVolumeMutable, IVolumePartiallyMutable } from './Volume';
-import type Serialiser from './Serialiser';
-
-export type LoadedPlugin = Partial<Plugin> & PluginModuleDefinition;
-
-/**
- * Plugins are lifecycle-based hooks that are called on every source at different stages.
- * Consumers will never need to invoke a lifecycle method; but for technical clarity - when a lifecycle method is called,
- * it will trigger `pluginRunner` which executes it on every source automatically.
- */
-type Plugin<ConfigData = {}, PluginOptions = {}, GlobalConfigData = ConfigData> = {
-  /**
-   * Plugin lifecycle method that triggers inside child processes.
-   * The first lifecycle hook to trigger after receiving pages from a source. The pages can safely be mutated and will be reflected in the final
-   * filesystem that gets generated.
-   * @param pages Array of pages from the source
-   * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
-   * @param param.config A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin
-   * @param options The options passed in when declaring the plugin
-   * @returns {Promise<Page[]>} Must re-return an array of `Page` objects, modified or not
-   */
-  $afterSource?(
-    pages: Page[],
-    {}: {
-      serialiser: Serialiser;
-      config: MutableData<ConfigData>;
-      pageExtensions: string[];
-      ignorePages: string[];
-    },
-    options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions
-  ): Promise<Page[]>;
-  /**
-   * Plugin lifecycle method that triggers inside child processes.
-   * Calls after a filesystem has been built up from the source pages.
-   * @param mutableFilesystem Mutable virtual filesystem instance with all of this source's pages inside (and symlinks applied)
-   * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
-   * @param param.config A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin
-   * @param options The options passed in when declaring the plugin
-   * @returns {void} No return expected
-   */
-  $beforeSend?(
-    mutableFilesystem: IVolumePartiallyMutable,
-    {}: {
-      serialiser: Serialiser;
-      pageExtensions: string[];
-      ignorePages: string[];
-      config: MutableData<ConfigData>;
-    },
-    options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions
-  ): Promise<void>;
-  /**
-   * Plugin lifecycle method that triggers inside the main process.
-   * Calls after the filesystem and symlinks have been reconstructed due to a change to the current source. This happens in the main thread.
-   * Pages will NOT be cached when read at this stage, to allow for reading content and writing a new copy of it without the cached version taking effect.
-   * This method is safe to use with lazy loading, as the filesystem should return the full page when read.
-   * NOTE: Plugin methods that trigger inside the parent process should be async and highly optimised to avoid holding up the main thread.
-   * You should also be mindful of race conditions when reading / writing to the global filesystem from this method - as other plugins may
-   * also have a read copy of the same file and it could end up out of sync.
-   * @param mutableFilesystem Mutable filesystem instance with all of this source's pages inside (and symlinks re-applied)
-   * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
-   * @param param.config An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. Shared only with this source.
-   * @param param.globalConfig An immutable object for reading data from other lifecycle phases of all plugins. Shared across all sources.
-   * @param param.sharedFilesystem Mutable filesystem instance independent of any sources. Useful for global pages, like sitemaps
-   * @param param.globalFilesystem Immutable union filesystem instance with all source's pages (and symlinks applied)
-   * @param options The options passed in when declaring the plugin
-   * @returns {void} No return expected
-   */
-  afterUpdate?(
-    mutableFilesystem: IVolumePartiallyMutable,
-    {}: {
-      serialiser: Serialiser;
-      config: ImmutableData<ConfigData>;
-      globalFilesystem: IUnionVolume;
-      sharedFilesystem: IVolumeMutable;
-      globalConfig: ImmutableData<GlobalConfigData>;
-      pageExtensions: string[];
-      ignorePages: string[];
-    },
-    options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions
-  ): Promise<void>;
-  /**
-   * Plugin lifecycle method that triggers inside the main process everytime ANY source emits new pages.
-   * This method should return a boolean that will indicate if this source should clear page caches.
-   * This method calls whenever another source (not this one) has changed.
-   * Returning `undefined`, false or no value, will result in the cache to be retained
-   * @param updatedSourceFilesystem Immutable filesystem for the source that changed
-   * @param param.config An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin
-   * @param param.serialiser A matching `Serialiser` for serialising/deserialising pages when reading/writing to the filesystem
-   * @param param.globalFilesystem Immutable union filesystem instance with all source's pages (and symlinks applied)
-   * @param options The options passed in when declaring the plugin
-   * @returns {Promise<boolean>} A boolean indicating whether to clear the cache for this source
-   */
-  shouldClearCache?(
-    updatedSourceFilesystem: IVolumeImmutable,
-    {}: {
-      serialiser: Serialiser;
-      config: ImmutableData<ConfigData>;
-      globalFilesystem: IUnionVolume;
-      pageExtensions: string[];
-      ignorePages: string[];
-    },
-    options?: Pick<PluginModuleDefinition, 'options'> & PluginOptions
-  ): Promise<boolean>;
-};
-
-export type LifecycleMethod = keyof Plugin;
-
-export default Plugin;

package/src/PluginModuleDefinition.ts

@@ -1,19 +0,0 @@
-export default interface PluginModuleDefinition {
-  /**
-   * Options to pass to the plugin lifecycle methods.
-   */
-  options: Record<string, unknown>;
-  /**
-   * The importance of this plugin. This highest number plugin will be run first
-   */
-  priority?: number;
-  /**
-   * Exclude this plugin when running `mosaic build`
-   */
-  runTimeOnly?: boolean;
-  /**
-   * Path to the JS file for this plugin (can either export a `default` module with lifecycle methods,
-   * or export the methods individually)
-   */
-  modulePath: string;
-}

package/src/PullDocsConfig.ts

@@ -1,11 +0,0 @@
-import PluginModuleDefinition from './PluginModuleDefinition';
-import SerialiserModuleDefinition from './SerialiserModuleDefinition';
-import SourceModuleDefinition from './SourceModuleDefinition';
-
-export interface PullDocsConfig {
-  pageExtensions: Array<string>;
-  ignorePages?: Array<string>;
-  serialisers: Array<SerialiserModuleDefinition>;
-  plugins: Array<PluginModuleDefinition>;
-  sources: Array<SourceModuleDefinition>;
-}

package/src/Serialiser.ts

@@ -1,31 +0,0 @@
-import type { TDataOut } from 'memfs/lib/encoding';
-
-import type Page from './Page';
-import type SerialiserModuleDefinition from './SerialiserModuleDefinition';
-
-/**
- * Serialisers are a form of plugin that tells PullDocs how to turn a file from/to a storable form for the filesystem
- * or a `Page` object.
- * For technical clarity - when a parser method is called, it will trigger `parserRunner` which checks the `fullPath` against
- * the `test` option that was passed in the PullDocs config file, to find a suitable parser.
- */
-export type Serialiser = {
-  /**
-   * Method to turn a raw page (e.g. an MDX file) into a `Page` object
-   * @param fullPath Route on virtual disk (should be full fullPath, not an alias)
-   * @param page Page in string or buffer form (i.e. an MDX page with frontmatter or a JSON file as a string)
-   * @returns Page object in the `Page` format
-   */
-  deserialise: (fullPath: string, page: TDataOut) => Promise<Page>;
-  /**
-   * Method to load a raw page from disk (e.g. an MDX file) and return into a `Page` object
-   * @param fullPath Route on virtual disk (should be full fullPath, not an alias)
-   * @param page Page in `Page` form
-   * @returns Page content
-   */
-  serialise: (fullPath: string, page: Page) => Promise<TDataOut>;
-};
-
-export type LoadedSerialiser = Serialiser & SerialiserModuleDefinition;
-
-export default Serialiser;

package/src/SerialiserModuleDefinition.ts

@@ -1,7 +0,0 @@
-import PluginModuleDefinition from './PluginModuleDefinition';
-
-type SerialiserModuleDefinition = PluginModuleDefinition & {
-  filter: RegExp;
-};
-
-export default SerialiserModuleDefinition;

package/src/Source.ts

@@ -1,13 +0,0 @@
-import type { Observable } from 'rxjs';
-
-import type Serialiser from './Serialiser';
-import type Page from './Page';
-
-type Source<Options = {}> = {
-  create(
-    options: Options,
-    { serialiser, pageExtensions }: { pageExtensions: string[]; serialiser: Serialiser }
-  ): Observable<Page[]>;
-};
-
-export default Source;

package/src/SourceModuleDefinition.ts

@@ -1,8 +0,0 @@
-import type PluginModuleDefinition from './PluginModuleDefinition';
-
-type SourceModuleDefinition = PluginModuleDefinition & {
-  namespace: string;
-  cache?: boolean;
-};
-
-export default SourceModuleDefinition;

package/src/Volume.ts

@@ -1,136 +0,0 @@
-import type {
-  DirectoryJSON,
-  IRealpathOptions,
-  IMkdirOptions,
-  IReaddirOptions,
-  TData,
-  TMode
-} from 'memfs/lib/volume';
-import type { TDataOut } from 'memfs/lib/encoding';
-import type Dirent from 'memfs/lib/Dirent';
-import type Stats from 'memfs/lib/Stats';
-import type { TStatNumber } from 'memfs/lib/Stats';
-import type { IStatOptions } from 'memfs/lib/volume';
-import type { PathLike, symlink } from 'fs';
-import type { Options, Pattern, Entry } from 'fast-glob';
-
-/**
- * Volumes are lightweight decorators which wrap `FileAccess` and limit access to the underlying API for different use-cases
- * Examples include disallowing mutation or allowing underlying functions like resetting
- */
-interface IVolume {
-  namespace: string;
-  reset?(): void;
-  toJSON(): DirectoryJSON;
-  symlinksToJSON(): { [key: string]: { target: string; type: string }[] };
-  fromJSON?(json: DirectoryJSON): void;
-  promises: {
-    exists(file: PathLike): Promise<boolean>;
-    glob(pattern: Pattern, options?: Options): Promise<string[] | Entry[]>;
-    mkdir(dir: PathLike, options?: TMode | IMkdirOptions): Promise<void>;
-    readdir(dir: PathLike, options?: string | IReaddirOptions): Promise<TDataOut[] | Dirent[]>;
-    readFile(file: PathLike): Promise<TDataOut>;
-    realpath(target: string, options?: string | IRealpathOptions): Promise<TDataOut>;
-    stat(file: PathLike, options?: IStatOptions): Promise<Stats<TStatNumber>>;
-    symlink(target: PathLike, alias: PathLike, type?: symlink.Type): Promise<void>;
-    unlink(target: PathLike): Promise<void>;
-    writeFile(file: PathLike, data: TData): Promise<void>;
-  };
-}
-export interface IVolumePartiallyMutable extends Omit<IVolume, 'reset' | 'fromJSON'> {
-  /**
-   * Functions that will be called after a page is read from the filesystem for the first time (since last cache clear).
-   * The value returned from this hook will *replace* the contents of the read file.
-   * @param hook Any function that invokes an `afterRead` plugin
-   * @returns Promise<Page>
-   */
-  __internal_do_not_use_addReadFileHook(
-    hook: (filepath: PathLike, fileData: TDataOut) => Promise<TDataOut>
-  ): void;
-}
-
-export interface IUnionVolume extends Omit<IVolumeImmutable, 'promises'> {
-  promises: Pick<IVolumeImmutable, 'promises'> & {
-    /**
-     * Reads a file
-     * @param file Path
-     * @returns Promise<TDataOut>
-     */
-    readFile(file: PathLike): Promise<TDataOut>;
-    readFile(file: PathLike, options?: { includeConflicts?: false }): Promise<TDataOut>;
-    /**
-     * Reads 1 or more files (if multiple files exist at the same location within the union filesystem)
-     * @param file Path
-     * @param options.includeConflicts If multiple files exist at the same location in the filesystem, return them all as an array
-     * @returns Promise<TDataOut[]>
-     */
-    readFile(file: PathLike, options: { includeConflicts: true }): Promise<TDataOut[]>;
-  };
-  /**
-   * Scopes a filesystem to specific namespaces
-   * @param {string[]} namespaces Array of namespaces to limit this filesystem to
-   * @returns A new immutable union filesystem
-   */
-  scope(namespaces: string[]): IUnionVolume;
-}
-
-export interface IVolumeMutable extends IVolume {
-  /**
-   * Functions that will be called after a page is read from the filesystem for the first time (since last cache clear).
-   * The value returned from this hook will *replace* the contents of the read file.
-   * @param hook Any function that invokes an `afterRead` plugin
-   * @returns Promise<Page>
-   */
-  __internal_do_not_use_addReadFileHook(
-    hook: (filepath: PathLike, fileData: TDataOut) => Promise<TDataOut>
-  ): void;
-  /**
-   * Restricted filesystems can be written to, but cannot be frozen, updated or reset
-   */
-  asRestricted(): IVolumePartiallyMutable;
-  /**
-   * ReadOnly filesystems cannot be mutated in any way, including freezing, updating or reseting
-   */
-  asReadOnly(): IVolumeImmutable;
-  /**
-   * Clears the filesystem's internal page cache - used when the cache may be outdated due to a source emiting new data or a dependency changing.
-   */
-  clearCache(): void;
-  /**
-   * Re-enables mutations on the underlying `FileAccess`.
-   */
-  unfreeze(): void;
-  /**
-   * Freezes an object, preventing all mutations on the underlying `FileAccess` object
-   * Freezing a filesystem indicates that the mutation period has ended and the file system can no longer be modified.
-   * When a filesystem is unfrozen, it is considered to be in flux, so may change as more plugins are called.
-   * When a filesystem is frozen, it is considered to be stable and ready to begin serving finalised versions of files.
-   */
-  freeze(): void;
-  /**
-   * Is this filesystem frozen/mutable?
-   * @returns {boolean}
-   */
-  get frozen(): boolean;
-  /**
-   * Appends content to the filesystem
-   * @param json A JSON blob in the form of {[fullPath]: "{fullPath: '', content: ''}"}
-   */
-  fromJSON(json: DirectoryJSON): void;
-  symlinksFromJSON(json: { [key: string]: { target: string; type: string }[] }): Promise<void>;
-  /**
-   * Completely resets the filesystem.
-   * This includes clearing page cache, erasing filesystem data, clearing symlinks etc
-   */
-  reset(): void;
-}
-export interface IVolumeImmutable
-  extends Omit<
-    IVolumePartiallyMutable,
-    'fromJSON' | 'reset' | 'promises' | '__internal_do_not_use_addReadFileHook'
-  > {
-  promises: Omit<
-    IVolume['promises'],
-    'writeFile' | 'symlink' | 'mkdir' | 'unlink' | 'rmdir' | 'rm' | 'rename'
-  >;
-}

package/src/WorkerData.ts

@@ -1,18 +0,0 @@
-import type SerialiserModuleDefinition from './SerialiserModuleDefinition';
-import type PluginModuleDefinition from './PluginModuleDefinition';
-import type SourceModuleDefinition from './SourceModuleDefinition';
-
-type WorkerData<Options = {}> = {
-  options: Options & Pick<PluginModuleDefinition, 'options'> & Pick<SourceModuleDefinition, 'options'> & {
-    pageExtensions: string[]
-  };
-  name: string;
-  namespace: string;
-  pageExtensions: string[];
-  ignorePages: string[];
-  plugins: PluginModuleDefinition[];
-  serialisers: SerialiserModuleDefinition[];
-  modulePath: string;
-};
-
-export default WorkerData;

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig",
-  "compilerOptions": {
-    "emitDeclarationOnly": true,
-    "rootDir": "./src",
-    "outDir": "./dist"
-  },
-  "include": ["src"],
-  "exclude": ["src/**/__tests__/**/*", "src/__tests__/**/*"]
-}