@codesoul-co/hypha-adapters-local / local-artifact-files

• Package index: @codesoul-co/hypha-adapters-local
• Source: packages/adapters-local/src/local-artifact-files.ts
• Exports: 17

Using this module

Use the Local artifact files module for using the public contracts and operations for this capability boundary. It exports 2 classes, 13 functions, 2 interfaces.

Import from the package entrypoint

import {
  LocalArtifactIntegrityError,
  LocalArtifactTransferAbortedError,
  ensureSafeLocalArtifactDirectory,
  ensureSafeLocalArtifactFile,
  hashLocalArtifactFile,
  isNodeError,
  listLocalArtifactFiles,
  localArtifactBlobPath,
} from '@codesoul-co/hypha-adapters-local';

import type {
  LocalArtifactStorePaths,
  LocalArtifactTempFile,
} from '@codesoul-co/hypha-adapters-local';

// The complete export list is documented below.

Usage patterns

• Use the 2 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 2 classes as constructable runtime implementations. Each symbol entry lists its constructor and public methods.
• The module exposes 13 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.

Public exports

Symbol	Kind	Signature	Description
LocalArtifactIntegrityError	class	new LocalArtifactIntegrityError(message: string): LocalArtifactIntegrityError	Local Artifact Integrity Error class with 8 public constructor or member entries; its exact declarations are listed below.
LocalArtifactTransferAbortedError	class	new LocalArtifactTransferAbortedError(): LocalArtifactTransferAbortedError	Local Artifact Transfer Aborted Error class with 9 public constructor or member entries; its exact declarations are listed below.
ensureSafeLocalArtifactDirectory	function	ensureSafeLocalArtifactDirectory(root: string, directory: string): Promise<void>	Ensure Safe Local Artifact Directory function with 1 public call signature; parameters and return types are listed below.
ensureSafeLocalArtifactFile	function	ensureSafeLocalArtifactFile(root: string, filename: string): Promise<void>	Ensure Safe Local Artifact File function with 1 public call signature; parameters and return types are listed below.
hashLocalArtifactFile	function	hashLocalArtifactFile(filename: string, root?: string, abortSignal?: AbortSignal): Promise<{ contentHash: string; sizeBytes: number; }>	Hash Local Artifact File function with 1 public call signature; parameters and return types are listed below.
isNodeError	function	isNodeError(error: unknown, code: string): boolean	Is Node Error function with 1 public call signature; parameters and return types are listed below.
listLocalArtifactFiles	function	listLocalArtifactFiles(root: string, extension?: string): Promise<string[]>	List Local Artifact Files function with 1 public call signature; parameters and return types are listed below.
localArtifactBlobPath	function	localArtifactBlobPath(paths: LocalArtifactStorePaths, contentHash: string): string	Local Artifact Blob Path function with 1 public call signature; parameters and return types are listed below.
localArtifactManifestPath	function	localArtifactManifestPath(paths: LocalArtifactStorePaths, objectKey: string): string	Local Artifact Manifest Path function with 1 public call signature; parameters and return types are listed below.
pathExists	function	pathExists(filename: string): Promise<boolean>	Path Exists function with 1 public call signature; parameters and return types are listed below.
prepareLocalArtifactStore	function	prepareLocalArtifactStore(rootPath: string): Promise<LocalArtifactStorePaths>	Prepare Local Artifact Store function with 1 public call signature; parameters and return types are listed below.
publishLocalArtifactBlob	function	publishLocalArtifactBlob(root: string, temporaryPath: string, blobPath: string, expectedHash: string, expectedSizeBytes: number): Promise<void>	Publish Local Artifact Blob function with 1 public call signature; parameters and return types are listed below.
streamLocalArtifactFile	function	streamLocalArtifactFile(filename: string, range?: ArtifactByteRange, root?: string, abortSignal?: AbortSignal): AsyncIterable<Uint8Array>	Stream Local Artifact File function with 1 public call signature; parameters and return types are listed below.
writeJsonAtomically	function	writeJsonAtomically(root: string, filename: string, value: unknown, options?: { ifAbsent?: boolean; }): Promise<void>	Write JSON Atomically function with 1 public call signature; parameters and return types are listed below.
writeLocalArtifactTempFile	function	writeLocalArtifactTempFile(source: ArtifactByteSource, paths: LocalArtifactStorePaths, maxBytes: number, abortSignal?: AbortSignal): Promise<LocalArtifactTempFile>	Write Local Artifact Temp File function with 1 public call signature; parameters and return types are listed below.
LocalArtifactStorePaths	interface	interface LocalArtifactStorePaths	Local Artifact Store Paths interface with 4 public fields or methods.
LocalArtifactTempFile	interface	interface LocalArtifactTempFile	Local Artifact Temp File interface with 3 public fields or methods.

LocalArtifactIntegrityError

Local Artifact Integrity Error class with 8 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { LocalArtifactIntegrityError } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare class LocalArtifactIntegrityError extends Error {
    constructor(message: string);
}

Public members

Member	Kind	Signature	Description
cause	property	cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
constructor	constructor	(message: string): LocalArtifactIntegrityError	Creates an instance of this class.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stack	property	stack?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
static captureStackTrace	method	static captureStackTrace(targetObject: object, constructorOpt?: Function): void	Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called. js const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack` The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance: js function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
static prepareStackTrace	method	static prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any	Public method; parameters and return type are shown in the signature.
static stackTraceLimit	property	static stackTraceLimit: number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

LocalArtifactTransferAbortedError

Local Artifact Transfer Aborted Error class with 9 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { LocalArtifactTransferAbortedError } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare class LocalArtifactTransferAbortedError extends Error {
    readonly code = "LOCAL_ARTIFACT_TRANSFER_ABORTED";
    constructor();
}

Public members

Member	Kind	Signature	Description
cause	property	cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
code	property	readonly code: "LOCAL_ARTIFACT_TRANSFER_ABORTED"	Public property; its type, readonly modifier and optionality are shown in the signature.
constructor	constructor	(): LocalArtifactTransferAbortedError	Creates an instance of this class.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stack	property	stack?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
static captureStackTrace	method	static captureStackTrace(targetObject: object, constructorOpt?: Function): void	Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called. js const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack` The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance: js function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
static prepareStackTrace	method	static prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any	Public method; parameters and return type are shown in the signature.
static stackTraceLimit	property	static stackTraceLimit: number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

ensureSafeLocalArtifactDirectory

Ensure Safe Local Artifact Directory function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { ensureSafeLocalArtifactDirectory } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function ensureSafeLocalArtifactDirectory(root: string, directory: string): Promise<void>;

Call signature

ensureSafeLocalArtifactDirectory(root: string, directory: string): Promise<void>

Parameters

Parameter	Type	Required	Description
root	string	Yes	Required parameter; accepted values are defined by the type column.
directory	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Promise<void>
• Description: The return contract is defined by the type shown above.

ensureSafeLocalArtifactFile

Ensure Safe Local Artifact File function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { ensureSafeLocalArtifactFile } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function ensureSafeLocalArtifactFile(root: string, filename: string): Promise<void>;

Call signature

ensureSafeLocalArtifactFile(root: string, filename: string): Promise<void>

Parameters

Parameter	Type	Required	Description
root	string	Yes	Required parameter; accepted values are defined by the type column.
filename	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Promise<void>
• Description: The return contract is defined by the type shown above.

hashLocalArtifactFile

Hash Local Artifact File function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { hashLocalArtifactFile } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function hashLocalArtifactFile(filename: string, root?: string, abortSignal?: AbortSignal): Promise<{
    contentHash: string;
    sizeBytes: number;
}>;

Call signature

hashLocalArtifactFile(filename: string, root?: string, abortSignal?: AbortSignal): Promise<{ contentHash: string; sizeBytes: number; }>

Parameters

Parameter	Type	Required	Description
filename	string	Yes	Required parameter; accepted values are defined by the type column.
root	string	No	Optional parameter; accepted values are defined by the type column.
abortSignal	AbortSignal	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: Promise<{ contentHash: string; sizeBytes: number; }>
• Description: The return contract is defined by the type shown above.

isNodeError

Is Node Error function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { isNodeError } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function isNodeError(error: unknown, code: string): boolean;

Call signature

isNodeError(error: unknown, code: string): boolean

Parameters

Parameter	Type	Required	Description
error	unknown	Yes	Required parameter; accepted values are defined by the type column.
code	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: boolean
• Description: The return contract is defined by the type shown above.

listLocalArtifactFiles

List Local Artifact Files function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { listLocalArtifactFiles } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function listLocalArtifactFiles(root: string, extension?: string): Promise<string[]>;

Call signature

listLocalArtifactFiles(root: string, extension?: string): Promise<string[]>

Parameters

Parameter	Type	Required	Description
root	string	Yes	Required parameter; accepted values are defined by the type column.
extension	string	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: Promise<string[]>
• Description: The return contract is defined by the type shown above.

localArtifactBlobPath

Local Artifact Blob Path function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { localArtifactBlobPath } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function localArtifactBlobPath(paths: LocalArtifactStorePaths, contentHash: string): string;

Call signature

localArtifactBlobPath(paths: LocalArtifactStorePaths, contentHash: string): string

Parameters

Parameter	Type	Required	Description
paths	LocalArtifactStorePaths	Yes	Required parameter; accepted values are defined by the type column.
contentHash	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: string
• Description: The return contract is defined by the type shown above.

localArtifactManifestPath

Local Artifact Manifest Path function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { localArtifactManifestPath } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function localArtifactManifestPath(paths: LocalArtifactStorePaths, objectKey: string): string;

Call signature

localArtifactManifestPath(paths: LocalArtifactStorePaths, objectKey: string): string

Parameters

Parameter	Type	Required	Description
paths	LocalArtifactStorePaths	Yes	Required parameter; accepted values are defined by the type column.
objectKey	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: string
• Description: The return contract is defined by the type shown above.

pathExists

Path Exists function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { pathExists } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function pathExists(filename: string): Promise<boolean>;

Call signature

pathExists(filename: string): Promise<boolean>

Parameters

Parameter	Type	Required	Description
filename	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Promise<boolean>
• Description: The return contract is defined by the type shown above.

prepareLocalArtifactStore

Prepare Local Artifact Store function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { prepareLocalArtifactStore } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function prepareLocalArtifactStore(rootPath: string): Promise<LocalArtifactStorePaths>;

Call signature

prepareLocalArtifactStore(rootPath: string): Promise<LocalArtifactStorePaths>

Parameters

Parameter	Type	Required	Description
rootPath	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Promise<LocalArtifactStorePaths>
• Description: The return contract is defined by the type shown above.

publishLocalArtifactBlob

Publish Local Artifact Blob function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { publishLocalArtifactBlob } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function publishLocalArtifactBlob(root: string, temporaryPath: string, blobPath: string, expectedHash: string, expectedSizeBytes: number): Promise<void>;

Call signature

publishLocalArtifactBlob(root: string, temporaryPath: string, blobPath: string, expectedHash: string, expectedSizeBytes: number): Promise<void>

Parameters

Parameter	Type	Required	Description
root	string	Yes	Required parameter; accepted values are defined by the type column.
temporaryPath	string	Yes	Required parameter; accepted values are defined by the type column.
blobPath	string	Yes	Required parameter; accepted values are defined by the type column.
expectedHash	string	Yes	Required parameter; accepted values are defined by the type column.
expectedSizeBytes	number	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Promise<void>
• Description: The return contract is defined by the type shown above.

streamLocalArtifactFile

Stream Local Artifact File function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { streamLocalArtifactFile } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function streamLocalArtifactFile(filename: string, range?: ArtifactByteRange, root?: string, abortSignal?: AbortSignal): AsyncIterable<Uint8Array>;

Call signature

streamLocalArtifactFile(filename: string, range?: ArtifactByteRange, root?: string, abortSignal?: AbortSignal): AsyncIterable<Uint8Array>

Parameters

Parameter	Type	Required	Description
filename	string	Yes	Required parameter; accepted values are defined by the type column.
range	ArtifactByteRange	No	Optional parameter; accepted values are defined by the type column.
root	string	No	Optional parameter; accepted values are defined by the type column.
abortSignal	AbortSignal	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: AsyncIterable<Uint8Array<ArrayBufferLike>>
• Description: The return contract is defined by the type shown above.

writeJsonAtomically

Write JSON Atomically function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { writeJsonAtomically } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function writeJsonAtomically(root: string, filename: string, value: unknown, options?: {
    ifAbsent?: boolean;
}): Promise<void>;

Call signature

writeJsonAtomically(root: string, filename: string, value: unknown, options?: { ifAbsent?: boolean; }): Promise<void>

Parameters

Parameter	Type	Required	Description
root	string	Yes	Required parameter; accepted values are defined by the type column.
filename	string	Yes	Required parameter; accepted values are defined by the type column.
value	unknown	Yes	Required parameter; accepted values are defined by the type column.
options	{ ifAbsent?: boolean; }	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: Promise<void>
• Description: The return contract is defined by the type shown above.

writeLocalArtifactTempFile

Write Local Artifact Temp File function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { writeLocalArtifactTempFile } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export declare function writeLocalArtifactTempFile(source: ArtifactByteSource, paths: LocalArtifactStorePaths, maxBytes: number, abortSignal?: AbortSignal): Promise<LocalArtifactTempFile>;

Call signature

writeLocalArtifactTempFile(source: ArtifactByteSource, paths: LocalArtifactStorePaths, maxBytes: number, abortSignal?: AbortSignal): Promise<LocalArtifactTempFile>

Parameters

Parameter	Type	Required	Description
source	ArtifactByteSource	Yes	Required parameter; accepted values are defined by the type column.
paths	LocalArtifactStorePaths	Yes	Required parameter; accepted values are defined by the type column.
maxBytes	number	Yes	Required parameter; accepted values are defined by the type column.
abortSignal	AbortSignal	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: Promise<LocalArtifactTempFile>
• Description: The return contract is defined by the type shown above.

LocalArtifactStorePaths

Local Artifact Store Paths interface with 4 public fields or methods.

• Kind: interface
• Import: import type { LocalArtifactStorePaths } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export interface LocalArtifactStorePaths {
    root: string;
    blobs: string;
    objects: string;
    temporary: string;
}

Contract members

Member	Kind	Signature	Description
blobs	property	blobs: string	Public property; its type, readonly modifier and optionality are shown in the signature.
objects	property	objects: string	Public property; its type, readonly modifier and optionality are shown in the signature.
root	property	root: string	Public property; its type, readonly modifier and optionality are shown in the signature.
temporary	property	temporary: string	Public property; its type, readonly modifier and optionality are shown in the signature.

LocalArtifactTempFile

Local Artifact Temp File interface with 3 public fields or methods.

• Kind: interface
• Import: import type { LocalArtifactTempFile } from '@codesoul-co/hypha-adapters-local';
• Source module: local-artifact-files

Declaration

export interface LocalArtifactTempFile {
    path: string;
    contentHash: string;
    sizeBytes: number;
}

Contract members

Member	Kind	Signature	Description
contentHash	property	contentHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
path	property	path: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.