build_cache.ts

view source

Declarations
#

12 declarations

BUILD_CACHE_METADATA_FILENAME
#

BUILD_CACHE_VERSION
#

BuildCacheMetadata
#

build_cache.ts view source

value + type

{ version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; } import {BuildCacheMetadata} from '@fuzdev/gro/build_cache.js';

Metadata stored in .gro/ directory to track build cache validity. Schema validates structure at load time to catch corrupted cache files.

version

type string

git_commit

type string | null

build_cache_config_hash

type string

timestamp

type string

outputs

type BuildOutputEntry[]

BuildOutputEntry
#

build_cache.ts view source

value + type

{ path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; } import {BuildOutputEntry} from '@fuzdev/gro/build_cache.js';

Metadata about a single build output file. Includes cryptographic hash for validation plus filesystem stats for debugging and optimization.

path

type string

hash

type string

size

type number

mtime

type number

ctime

type number

mode

type number

collect_build_outputs
#

build_cache.ts view source

(build_dirs: string[]): Promise<{ path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]> import {collect_build_outputs} from '@fuzdev/gro/build_cache.js';

Collects information about all files in build output directories. Returns an array of entries with path, hash, size, mtime, ctime, and mode.

Files are hashed in parallel for performance. For very large builds (10k+ files), this may take several seconds but ensures complete cache validation.

build_dirs

array of output directories to scan (e.g., ['build', 'dist', 'dist_server'])

type string[]

returns

Promise<BuildOutputEntry[]>

compute_build_cache_key
#

build_cache.ts view source

(config: GroConfig, log: Logger, git_commit?: string | null | undefined): Promise<{ git_commit: string | null; build_cache_config_hash: string; }> import {compute_build_cache_key} from '@fuzdev/gro/build_cache.js';

Computes the cache key components for a build. This determines whether a cached build can be reused.

config

Gro config (build_cache_config_hash is already computed during config load)

type GroConfig

log

Logger

type Logger

git_commit?

optional pre-computed git commit hash (optimization to avoid re-reading)

type string | null
optional

returns

Promise<{ git_commit: string | null; build_cache_config_hash: string; }>

create_build_cache_metadata
#

build_cache.ts view source

(config: GroConfig, log: Logger, git_commit?: string | null | undefined, build_dirs?: string[] | undefined): Promise<{ version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { ...; }[]; }> import {create_build_cache_metadata} from '@fuzdev/gro/build_cache.js';

Creates build cache metadata after a successful build. Automatically discovers all build output directories (build/, dist/, dist_*).

config

Gro config

type GroConfig

log

Logger

type Logger

git_commit?

optional pre-computed git commit hash (optimization)

type string | null
optional

build_dirs?

optional pre-discovered build directories (optimization to avoid redundant filesystem scans)

type string[]
optional

returns

Promise<BuildCacheMetadata>

discover_build_output_dirs
#

build_cache.ts view source

(): Promise<string[]> import {discover_build_output_dirs} from '@fuzdev/gro/build_cache.js';

Discovers all build output directories in the current working directory. Returns an array of directory names that exist: build/, dist/, dist_*

returns

Promise<string[]>

is_build_cache_valid
#

build_cache.ts view source

(config: GroConfig, log: Logger, git_commit?: string | null | undefined): Promise<boolean> import {is_build_cache_valid} from '@fuzdev/gro/build_cache.js';

Main function to check if the build cache is valid. Returns true if the cached build can be used, false if a fresh build is needed.

config

Gro config

type GroConfig

log

Logger

type Logger

git_commit?

optional pre-computed git commit hash (optimization)

type string | null
optional

returns

Promise<boolean>

load_build_cache_metadata
#

build_cache.ts view source

(): Promise<{ version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; } | null> import {load_build_cache_metadata} from '@fuzdev/gro/build_cache.js';

Loads build cache metadata from .gro/ directory. Invalid or corrupted cache files are automatically deleted.

returns

Promise<BuildCacheMetadata | null>

save_build_cache_metadata
#

build_cache.ts view source

(metadata: { version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; }, log?: Logger | undefined): Promise<...> import {save_build_cache_metadata} from '@fuzdev/gro/build_cache.js';

Saves build cache metadata to .gro/ directory. Errors are logged but don't fail the build (cache is optional).

metadata

type BuildCacheMetadata

log?

type Logger
optional

returns

Promise<void>

validate_build_cache
#

build_cache.ts view source

(metadata: { version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; }): Promise<...> import {validate_build_cache} from '@fuzdev/gro/build_cache.js';

Validates that a cached build is still valid by checking stats and hashing outputs. Uses size as a fast negative check before expensive hashing. This is comprehensive validation to catch manual tampering or corruption.

metadata

type BuildCacheMetadata

returns

Promise<boolean>

Depends on
#

Imported by
#