@openfairygui/functions

Composable authoring workflows and thin application seams built on top of @openfairygui/core.

Install

npm install --save @openfairygui/core @openfairygui/functions

Usage

import { NodeIO } from '@openfairygui/core/node';
import { inspect } from '@openfairygui/functions';
import { publishNode, restoreNode, validateProjectNode } from '@openfairygui/functions/node';

const io = new NodeIO();
const doc = await io.readProject('./MyProject/MyProject.fairy');

const report = inspect(doc);
const validation = await validateProjectNode('./MyProject/MyProject.fairy');
const published = await publishNode({ document: doc, output: './release' });
console.log(published.files); // Actual writes: final absolute paths and byte sizes.

await restoreNode({
	inputDir: './release',
	output: './restored-project',
});

validateProjectNode combines detailed project reads, UAM integrity checks, source checks, and Sharp image decoding without writing files. publishNode owns the standard Node filesystem, Sharp raster backend, and project plugin discovery. restoreNode owns the Node filesystem and Sharp image extraction required by trusted-local artifact recovery. The root validateProject(), publish(), and restore() exports remain lower-level workflows for custom hosts.

Browser LayaBox publish

Use @openfairygui/core/web to read the raw project, then publish through the browser-only entry. Both filesystems are caller-owned, so they can be File System Access, OPFS, IndexedDB, ZIP, or memory adapters.

import { liftDocumentToUamProject } from '@openfairygui/core';
import { WebIO } from '@openfairygui/core/web';
import { publishBrowser, validateProjectWeb } from '@openfairygui/functions/web';

const document = await new WebIO(sourceFileSystem).readProject('Project.fairy', { hydrateResourceBytes: true });
const validation = await validateProjectWeb(liftDocumentToUamProject(document));
const result = await publishBrowser({
	document,
	sourceFileSystem,
	outputFileSystem,
	projectType: 'layabox',
	output: '.fairygui-runtime',
});

if (!result.success) console.error(result.diagnostics);

The browser entry uses native Canvas APIs for atlas PNGs, writes only through outputFileSystem, and supplies no Node plugin capability. Persisted Laya publish compression, atlas, and safe file-extension settings apply; explicit compressed and atlas options override their corresponding settings. Explicit output, branch, and packages also keep their normal precedence, so desktop-only configured output paths are not used when output is supplied.

Browser code generation is not supported. If global code generation is enabled and a selected package requests it, preflight returns unsupported_publish_setting with setting and path before Canvas checks or output writes. On any failure, files lists only writeFileRaw operations that completed successfully; success: false with a non-empty list therefore means built-in output is partial. Callers needing atomic publication should provide a transactional or staging outputFileSystem.

Publish plugins are documented in the repository guide:

• https://github.com/OpenFairyGUI/OpenFairyGUI/blob/main/docs/publish-plugins.md

UAM authoring seam

@openfairygui/functions also exposes a thin stateless wrapper over the UAM transaction contract from @openfairygui/core.

This seam:

• accepts UamProject + UamTransactionOperation[]
• returns structured app-level success / failure results
• does not expose Document
• does not define a second selector / operation grammar
• does not wrap publish or restore

The transaction surface includes component size/root properties, component-instance extension overlays, resource rename/move, complete image-resource property snapshots, byte-backed binary resource add/replace/remove, and add/update/remove for display, display2, look, xy, size, color, animation, text, icon, and fontSize gears. Resource rename/move/replace/remove requires sourceBytes; opt in with ProjectReader.read(path, { hydrateResourceBytes: true }) before lifting a project to UAM. Source bytes are written back with the project, and stale source files are removed only after all replacement content succeeds.

import {
	type UamProject,
	type UamTransactionOperation,
} from '@openfairygui/core';
import { applyUamTransactionApp } from '@openfairygui/functions';

const project: UamProject = /* project read and lifted with hydrateResourceBytes */;
const operations: UamTransactionOperation[] = [
	{
		kind: 'renameResource',
		selector: { packageId: 'pkg001', resourceId: 'img001' },
		newName: 'renamed.png',
	},
];

const result = applyUamTransactionApp({ project, operations });
if (!result.ok) {
	console.error(result.error.code, result.error.stage, result.error.message);
}

Repository:

• https://github.com/OpenFairyGUI/OpenFairyGUI