@ferolyte/common

Shared utilities and content foundation for the Ferolyte framework.

This package provides TypeScript types, content validation, diagnostic reporting, object utilities, and small data structures used by @ferolyte/pack and @ferolyte/cli.

Installation

npm install @ferolyte/common

This package is usually installed as a transitive dependency of @ferolyte/pack or @ferolyte/cli. Install it directly when building custom tooling on top of Ferolyte.

Requirements: Node.js >= 18

Feature scope

Types

| Export | Path | Description | | ------------------- | ---------------------------------------------------- | ------------------------------------------------------ | | Identifier | @ferolyte/common/types/core/identifier | Typed namespace:id string for Minecraft content IDs | | RequireAtLeastOne | @ferolyte/common/types/object/require-at-least-one | Utility type requiring at least one key from an object | | OneOfRecord | @ferolyte/common/types/core/one-of-record | Discriminated union of single-key records | | IntRange | @ferolyte/common/types/number/int-range | Compile-time integer range type | | LooseString<T> | @ferolyte/common/types/core/loose-string | Known literals as suggestions, any string accepted |

Content foundation

| Export | Path | Description | | ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------ | | ContentBuilder | @ferolyte/common/content/interfaces/content-builder | Contract for Ferolyte content modules (metadata, cloneConfig(), build()) | | CONTENT_METADATA | @ferolyte/common/content/metadata | Tags for item, block, server/client entity and BP/RP animation controller types |

Diagnostics

Structured diagnostics with file links, camelCase field paths and content-type labels. A sink collects them as records (used by ferolyte check --json / run --json).

| Export | Path | | --- | --- | | ContentDiagnosticContext, ContentDiagnosticRecord, ContentDiagnosticSeverity, ContentType, ContentSection | @ferolyte/common/content/diagnostics/content-diagnostic | | logContentError, logContentWarning, reportContentFailure, reportDiagnosticRecord | @ferolyte/common/content/diagnostics/content-diagnostic | | setContentDiagnosticSink, getContentDiagnosticSink | @ferolyte/common/content/diagnostics/content-diagnostic | | buildFieldPath, createFileLink, withFieldPath, withComponentContext, withSectionContext | @ferolyte/common/content/diagnostics/content-diagnostic | | hintSnakeCaseComponent, hintSnakeCaseFields, isSnakeCase, snakeToCamel | @ferolyte/common/content/diagnostics/snake-case-hint |

Validation

Type-guard validators for hand-written SDK sugar (generated components are validated by precompiled schema validators in @ferolyte/pack). They report through the diagnostics context on failure:

validateBooleanValue, validateString, validateNonEmptyString, validateNumber, validateNumberRange, validateAllowedValue, validateNonEmptyArray, validateVector. Import from @ferolyte/common/content/validation/content-validation.

Localization and versions

| Export | Path | Description | | --- | --- | --- | | LocalizedString, Locale, toTranslations, isValidLocalizedString | @ferolyte/common/content/localization/localized-string | string or { en_US, ru_RU, … } for displayName → .lang | | compareVersions, isVersionAtLeast | @ferolyte/common/content/versions/compare-version | format_version comparison for version-gated fields |

Content tools

| Export | Path | Description | | ------- | -------------------------------------- | -------------------------------------------------- | | Float | @ferolyte/common/content/tools/float | Serializes floats for JSON round-trip during build |

Minecraft types

| Export | Path | Description | | ------------------- | ----------------------------------------------------- | ----------------------------------- | | MinecraftPackType | @ferolyte/common/content/types/minecraft-pack-types | 'BP' \| 'RP' pack type | | DamageSourceType | @ferolyte/common/content/types/damage-source | Union of 37 Minecraft damage causes |

Object utilities

| Export | Path | Description | | ---------------- | ----------------------------------------- | ----------------------------------- | | deepMerge | @ferolyte/common/object/deep-merge | Recursive merge; arrays concatenate | | cartesianMerge | @ferolyte/common/object/cartesian-merge | Cartesian product of option objects |

Data structures

| Export | Path | Description | | ------------------------------------------ | ---------------------------------------------------- | -------------------------- | | ArrayQueue, createArrayQueue | @ferolyte/common/data-structures/array-queue | Simple array-backed queue | | RingBufferQueue, createRingBufferQueue | @ferolyte/common/data-structures/ring-buffer-queue | Fixed-capacity ring buffer |

Shapes

| Export | Path | Description | | ------------------------ | ------------------------------------------------- | --------------------------------------------------------- | | createDiamondLocations | @ferolyte/common/shape/create-diamond-locations | Horizontal diamond of Vector3 positions around a center |

License

MIT © 2024 Lexon2. See LICENSE.