@dereekb/rxjs 13.6.9 → 13.6.11

package/src/lib/asset/asset.builder.d.ts

@@ -0,0 +1,112 @@
+import { type SlashPath, type WebsiteUrlWithPrefix } from '@dereekb/util';
+import { type AssetLocalPathRef, type AssetRemotePathRef } from './asset';
+/**
+ * Creates a local {@link AssetLocalPathRef}.
+ *
+ * @example
+ * ```ts
+ * const DISTRICTS = localAsset('data/school-districts.json');
+ * // { sourceType: 'local', path: 'data/school-districts.json' }
+ * ```
+ *
+ * @param path - Relative path from the environment's base asset directory.
+ */
+export declare function localAsset(path: SlashPath): AssetLocalPathRef;
+/**
+ * Creates a remote {@link AssetRemotePathRef}.
+ *
+ * Remote assets always use absolute URLs with an http:// or https:// prefix.
+ * Throws if the provided URL does not have a valid prefix.
+ *
+ * @example
+ * ```ts
+ * const CDN = remoteAsset('https://cdn.example.com/geo.json');
+ * // { sourceType: 'remote', url: 'https://cdn.example.com/geo.json' }
+ * ```
+ *
+ * @param url - Absolute URL with http/https prefix to fetch the asset from.
+ * @throws Error if the URL does not have a valid http/https prefix.
+ */
+export declare function remoteAsset(url: WebsiteUrlWithPrefix): AssetRemotePathRef;
+/**
+ * Fluent builder returned by {@link assetFolder} for creating multiple
+ * local asset refs from the same folder.
+ */
+export interface AssetFolderBuilder {
+    /**
+     * Creates a single local ref for a file in this folder.
+     *
+     * @param path - Relative path within the folder.
+     */
+    asset(path: SlashPath): AssetLocalPathRef;
+    /**
+     * Creates local refs for multiple files in this folder.
+     *
+     * @param paths - Array of relative paths within the folder.
+     */
+    assets(paths: readonly SlashPath[]): AssetLocalPathRef[];
+}
+/**
+ * Creates a fluent builder for creating multiple local asset refs
+ * from the same folder.
+ *
+ * @example
+ * ```ts
+ * const DATA = assetFolder('data');
+ *
+ * const DISTRICTS = DATA.asset('school-districts.json');
+ * // { sourceType: 'local', path: 'data/school-districts.json' }
+ *
+ * const [A, B] = DATA.assets(['a.txt', 'b.txt']);
+ * // [
+ * //   { sourceType: 'local', path: 'data/a.txt' },
+ * //   { sourceType: 'local', path: 'data/b.txt' }
+ * // ]
+ * ```
+ *
+ * @param folder - Base folder path for the assets.
+ */
+export declare function assetFolder(folder: SlashPath): AssetFolderBuilder;
+/**
+ * Fluent builder returned by {@link remoteAssetBaseUrl} for creating
+ * multiple remote asset refs from the same base URL.
+ */
+export interface RemoteAssetBuilder {
+    /**
+     * Creates a single remote ref for a path relative to the base URL.
+     *
+     * @param path - Relative path appended to the base URL.
+     */
+    asset(path: SlashPath): AssetRemotePathRef;
+    /**
+     * Creates remote refs for multiple paths relative to the base URL.
+     *
+     * @param paths - Array of relative paths appended to the base URL.
+     */
+    assets(paths: readonly SlashPath[]): AssetRemotePathRef[];
+}
+/**
+ * Creates a fluent builder for creating multiple remote asset refs
+ * from the same base URL.
+ *
+ * The base URL must be a valid {@link WebsiteUrlWithPrefix}.
+ * Each child path is appended to produce a full absolute URL.
+ *
+ * @example
+ * ```ts
+ * const CDN = remoteAssetBaseUrl('https://cdn.example.com/assets');
+ *
+ * const GEO = CDN.asset('data/geo.json');
+ * // { sourceType: 'remote', url: 'https://cdn.example.com/assets/data/geo.json' }
+ *
+ * const [A, B] = CDN.assets(['a.json', 'b.json']);
+ * // [
+ * //   { sourceType: 'remote', url: 'https://cdn.example.com/assets/a.json' },
+ * //   { sourceType: 'remote', url: 'https://cdn.example.com/assets/b.json' }
+ * // ]
+ * ```
+ *
+ * @param baseUrl - Base URL with http/https prefix.
+ * @throws Error if the base URL does not have a valid http/https prefix.
+ */
+export declare function remoteAssetBaseUrl(baseUrl: WebsiteUrlWithPrefix): RemoteAssetBuilder;

package/src/lib/asset/asset.d.ts

@@ -0,0 +1,114 @@
+import { type SlashPath, type WebsiteUrl } from '@dereekb/util';
+import { type Observable } from 'rxjs';
+/**
+ * Discriminator for how an asset's source should be resolved.
+ *
+ * - `'local'` — bundled file resolved relative to an environment-specific base path
+ * - `'remote'` — fetched via HTTP(S) from an absolute URL
+ */
+export type AssetSourceType = 'local' | 'remote';
+/**
+ * Self-describing reference to an asset. Carries all the information
+ * a loader needs to resolve and load the asset's data.
+ *
+ * Used directly as the argument to {@link AssetLoader.get}.
+ *
+ * @example
+ * ```ts
+ * const DISTRICTS = localAsset('data/school-districts.json');
+ * const GEO = remoteAsset('https://cdn.example.com/geo.json');
+ *
+ * const instance = loader.get(DISTRICTS);
+ * instance.load().subscribe((buffer) => { ... });
+ * ```
+ */
+export type AssetPathRef = AssetLocalPathRef | AssetRemotePathRef;
+/**
+ * Reference to a local/bundled asset file.
+ * The loader resolves {@link path} relative to its configured local base path.
+ */
+export interface AssetLocalPathRef {
+    readonly sourceType: 'local';
+    /**
+     * Relative path from the environment's base asset directory.
+     *
+     * @example `'data/school-districts.json'`
+     */
+    readonly path: SlashPath;
+}
+/**
+ * Reference to a remote asset fetched via HTTP(S).
+ *
+ * The {@link url} is always an absolute {@link WebsiteUrl}
+ * (e.g., `'https://cdn.example.com/geo.json'`).
+ *
+ * Any relative asset path should use {@link AssetLocalPathRef} instead.
+ */
+export interface AssetRemotePathRef {
+    readonly sourceType: 'remote';
+    /**
+     * Absolute URL to fetch the asset from.
+     *
+     * @example `'https://cdn.example.com/geo.json'`
+     */
+    readonly url: WebsiteUrl;
+}
+/**
+ * Instance returned by {@link AssetLoader.get} for a specific asset.
+ *
+ * Decouples ref lookup from data loading — callers can hold an instance
+ * and load lazily via the Observable.
+ *
+ * @example
+ * ```ts
+ * const instance = loader.get(PROJECT_ASSETS.DISTRICTS);
+ * instance.ref();  // AssetLocalPathRef
+ * instance.load().subscribe((buffer) => { ... });
+ * ```
+ */
+export interface AssetLoaderAssetInstance {
+    /**
+     * Returns the {@link AssetPathRef} this instance was created for.
+     */
+    ref(): AssetPathRef;
+    /**
+     * Loads the raw bytes of the asset.
+     *
+     * Returns a cold Observable — the load is triggered on each subscription.
+     */
+    load(): Observable<ArrayBuffer>;
+}
+/**
+ * Promise-based function signature for a leaf asset loader.
+ *
+ * Used internally by environment-specific loaders (filesystem, fetch, etc.)
+ * and composed via {@link delegatedAssetLoader}.
+ */
+export type AssetLoaderGetFn = (ref: AssetPathRef) => Promise<ArrayBuffer>;
+/**
+ * Abstract asset loader that serves as a DI token in both Angular and NestJS.
+ *
+ * Accepts an {@link AssetPathRef} and returns an {@link AssetLoaderAssetInstance}
+ * for lazy Observable-based loading.
+ *
+ * Follows the same abstract-class-as-DI-token pattern as StorageObject.
+ * All concrete implementations are functional (factory functions returning
+ * objects satisfying this contract), except Angular's DbxCoreAssetLoader
+ * which requires @Injectable().
+ *
+ * @example
+ * ```ts
+ * // Angular: inject(AssetLoader)
+ * // NestJS:  @Inject(AssetLoader)
+ * const instance = loader.get(PROJECT_ASSETS.SCHOOL_DISTRICTS);
+ * instance.load().subscribe((data) => { ... });
+ * ```
+ */
+export declare abstract class AssetLoader {
+    /**
+     * Returns an {@link AssetLoaderAssetInstance} for the given ref.
+     *
+     * @param ref - Self-describing asset path reference (local or remote).
+     */
+    abstract get(ref: AssetPathRef): AssetLoaderAssetInstance;
+}

package/src/lib/asset/asset.loader.d.ts

@@ -0,0 +1,34 @@
+import { type AssetPathRef, type AssetLoaderAssetInstance, type AssetLoaderGetFn, AssetLoader } from './asset';
+/**
+ * Creates an {@link AssetLoaderAssetInstance} from a ref and a Promise-based get function.
+ *
+ * The returned {@link AssetLoaderAssetInstance.load} observable is cold — each subscription
+ * invokes the get function anew.
+ *
+ * @example
+ * ```ts
+ * const instance = assetLoaderAssetInstance(ref, (r) => fetch(r.path).then(res => res.arrayBuffer()));
+ * instance.load().subscribe((data) => { ... });
+ * ```
+ *
+ * @param ref - The asset path reference this instance represents.
+ * @param getFn - Promise-based function that loads the asset bytes.
+ */
+export declare function assetLoaderAssetInstance(ref: AssetPathRef, getFn: AssetLoaderGetFn): AssetLoaderAssetInstance;
+/**
+ * Creates an {@link AssetLoader} from a single {@link AssetLoaderGetFn}.
+ *
+ * This is the primary helper for building functional AssetLoader implementations
+ * from a Promise-based leaf loader.
+ *
+ * @example
+ * ```ts
+ * const loader = assetLoaderFromGetFn(async (ref) => {
+ *   const response = await fetch(resolveUrl(ref));
+ *   return response.arrayBuffer();
+ * });
+ * ```
+ *
+ * @param getFn - Promise-based function that loads any asset's bytes.
+ */
+export declare function assetLoaderFromGetFn(getFn: AssetLoaderGetFn): AssetLoader;

package/src/lib/asset/asset.loader.delegated.d.ts

@@ -0,0 +1,36 @@
+import { AssetLoader } from './asset';
+/**
+ * Configuration for {@link delegatedAssetLoader}.
+ * Specifies which loader handles each source type.
+ */
+export interface DelegatedAssetLoaderConfig {
+    /**
+     * Loader for {@link AssetLocalPathRef} assets (e.g., filesystem reads).
+     */
+    readonly local: AssetLoader;
+    /**
+     * Loader for {@link AssetRemotePathRef} assets (e.g., HTTP fetch).
+     */
+    readonly remote: AssetLoader;
+}
+/**
+ * Creates an {@link AssetLoader} that delegates to source-type-specific loaders.
+ *
+ * This is the primary composition point: wire a local loader and a remote
+ * loader together, and the delegated loader routes each {@link AssetPathRef}
+ * to the correct one based on {@link AssetPathRef.sourceType}.
+ *
+ * @example
+ * ```ts
+ * const loader = delegatedAssetLoader({
+ *   local: nodeJsLocalAssetLoader({ basePath: './assets' }),
+ *   remote: fetchAssetLoader({ baseUrl: 'https://api.example.com/assets/' })
+ * });
+ *
+ * loader.get(localAsset('data/districts.json'));   // → local loader
+ * loader.get(remoteAsset('data/geo.json'));        // → remote loader
+ * ```
+ *
+ * @param config - Specifies the local and remote delegate loaders.
+ */
+export declare function delegatedAssetLoader(config: DelegatedAssetLoaderConfig): AssetLoader;

package/src/lib/asset/asset.loader.fetch.d.ts

@@ -0,0 +1,33 @@
+import { AssetLoader } from './asset';
+/**
+ * Configuration for {@link fetchAssetLoader}.
+ */
+export interface FetchAssetLoaderConfig {
+    /**
+     * Optional pre-configured fetch function.
+     * Defaults to the global `fetch` if not provided.
+     *
+     * Useful for injecting auth headers, timeouts, or test mocks.
+     */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Creates an {@link AssetLoader} that loads remote assets via HTTP fetch.
+ * Works in both browser and Node.js (Node 18+) environments.
+ *
+ * Remote refs always have absolute URLs, so no base URL resolution is needed.
+ *
+ * @example
+ * ```ts
+ * const loader = fetchAssetLoader();
+ * loader.get(remoteAsset('https://cdn.example.com/geo.json')).load().subscribe((data) => {
+ *   // loaded from https://cdn.example.com/geo.json
+ * });
+ *
+ * // With a custom fetch function:
+ * const loader = fetchAssetLoader({ fetch: myAuthenticatedFetch });
+ * ```
+ *
+ * @param config - Optional fetch configuration with custom fetch function.
+ */
+export declare function fetchAssetLoader(config?: FetchAssetLoaderConfig): AssetLoader;

package/src/lib/asset/asset.loader.memory.d.ts

@@ -0,0 +1,21 @@
+import { type AssetPathRef, AssetLoader } from './asset';
+/**
+ * Creates an {@link AssetLoader} backed by an in-memory map.
+ * Useful for testing without filesystem or network access.
+ *
+ * Assets are matched by reference identity — the same {@link AssetPathRef}
+ * object used to populate the map must be used to retrieve the data.
+ *
+ * @example
+ * ```ts
+ * const DISTRICTS = localAsset('districts.json');
+ * const loader = memoryAssetLoader(new Map([
+ *   [DISTRICTS, new TextEncoder().encode('[]').buffer]
+ * ]));
+ *
+ * loader.get(DISTRICTS).load().subscribe((data) => { ... });
+ * ```
+ *
+ * @param assets - Map of asset refs to their raw byte data.
+ */
+export declare function memoryAssetLoader(assets: Map<AssetPathRef, ArrayBuffer>): AssetLoader;

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

@@ -0,0 +1,6 @@
+export * from './asset';
+export * from './asset.builder';
+export * from './asset.loader';
+export * from './asset.loader.delegated';
+export * from './asset.loader.fetch';
+export * from './asset.loader.memory';

package/src/lib/index.d.ts

@@ -1,3 +1,4 @@
+export * from './asset';
 export * from './filter';
 export * from './iterator';
 export * from './loading';