Collecting external resources

E.g., import external graphics or possibly other resources.

import { ResourceCollector } from '@phfaist/zoodb/resourcecollector';
class ResourceCollector()

Main manager class for collecting external resources (e.g. graphics files) referenced by zoo objects.

Resources are keyed by resource type (an application-defined string such as ‘graphics’). For each type the collector delegates to:

  • A resource retriever (e.g. FilesystemResourceRetriever()) that locates the resource, copies it to a target location if needed, and returns a target_info object.

  • Zero or more resource processors that receive { target_info, source, processed_info } and can add arbitrary properties to processed_info.

Constructor options:

  • resource_types (required) — array of resource type name strings.

  • resource_retrievers — object mapping each resource type name to its retriever instance.

  • resource_processors — object mapping each resource type name to an array of processor instances.

ResourceCollector.ResourceCollector
ResourceCollector.collect(resource_type, source)

Collect the resource identified by source of type resource_type.

Resolves the source via the registered retriever, then runs all registered processors for that type. If the resource was already collected (either by its canonical name or as an alias), this call is a no-op.

Important: collect() calls must be awaited and must not run concurrently — if a second call is made before the first resolves, an error is thrown.

Arguments:

  • resource_type (string) – The resource type (must be listed in options.resource_types).

  • source (string) – The source identifier (e.g. a file path) for the resource to collect.

Returns:

Promise.<void> –

ResourceCollector.finish()

Signal to all registered resource retrievers that collection is complete. Calls retriever.finish() on every retriever in parallel.

Returns:

Promise.<void> –

ResourceCollector.get_resource_data(resource_type, source)

Return the collected resource data object for the given resource_type and source. Alias sources are resolved to their canonical name automatically.

Returns undefined if the resource has not yet been collected.

Arguments:

  • resource_type (string) – The resource type.

  • source (string) – The source identifier (may be an alias).

Returns:

Object|undefined –

Resource Retrievers

import {
    FilesystemResourceRetriever
} from '@phfaist/zoodb/resourcecollector/retriever/fs';

(There might be more retrievers in the future.)

class FilesystemResourceRetriever()

Resource retriever that locates files on the local filesystem and, optionally, copies them to a target output directory with a renamed filename derived from the file’s content hash.

Constructor options:

  • fs (required) — filesystem access object. Must provide access() and readFile() (needed when the rename template uses a content hash). fs.promises can hold pre-promisified versions of these methods. When copy_to_target_directory is true, mkdir() and copyFile(src, dest) are also required.

  • copy_to_target_directory — when true, each retrieved file is copied from source_directory to target_directory using the name produced by rename_file_template. Defaults to false.

  • source_directory — base directory for resolving source paths (default: ‘.’).

  • target_directory — directory that files are copied into when copy_to_target_directory is true (default: ‘./_output_file_resources/’).

  • rename_file_template — a function (accessor) → string that produces the target filename from a FilesystemPropertiesAccessor instance (which exposes helpers like b32hash(), lowerext(), etc.). Defaults to (f) => `fig-${f.b32hash(24)}${f.lowerext()}`.

  • rename_use_file_hash — when true (default) the file content is read so that the rename template can use content hashes. Set to false to skip reading the file if the rename template does not use hashes.

  • read_file_content — set to true to read the file content unconditionally (independently of rename_use_file_hash).

  • extensions — array of filename extensions to try when resolving a source name that lacks an extension. Include ‘’ to try the bare name as-is. Defaults to [‘’].

FilesystemResourceRetriever.FilesystemResourceRetriever

Resource Processors

import {
    FLMGraphicsResourceProcessor
} from '@phfaist/zoodb/resourcecollector/processor/flmgraphicsprocessor';

(There might be more processors in the future.)

class FLMGraphicsResourceProcessor()

Process graphics to extract physical image dimensions, resolution, and other information.

FLMGraphicsResourceProcessor.FLMGraphicsResourceProcessor