l0.DependencyControl.UpdateFeed¶

MoonScriptLua

UpdateFeed = require "l0.DependencyControl.UpdateFeed"

local UpdateFeed = require("l0.DependencyControl.UpdateFeed")

UpdateFeed ¶

Downloaded and expanded update feed data source.

Constructor ¶

MoonScriptLua

updateFeed = UpdateFeed url, autoLoad, fileName, config, logger

local updateFeed = UpdateFeed(url, autoLoad, fileName, config, logger)

Creates an update feed wrapper and optionally fetches feed data. Raises when neither a URL nor a file name is given.

param	type	description
url?	`string`	Feed URL (or nil when loading from a local file via fileName).
autoLoad?	`boolean`	Fetch/load the feed immediately (default true).
fileName?	`string`	Local feed file path.
config?	`table`	Feed-fetch settings, normally supplied by `FeedLoader`: `cache` (the on-disk `FileCache`) and `blockPrivateHosts`.
logger?	Logger

Instance methods¶

getKnownFeeds ¶

Deprecated — Use the knownFeeds property. Retained for callers written against DepCtrl < 0.7.

MoonScriptLua

updateFeed\getKnownFeeds!

updateFeed:getKnownFeeds()

Returns:

urls string[]

fetch ¶

MoonScriptLua

updateFeed\fetch fileName, expansionMode

updateFeed:fetch(fileName, expansionMode)

Downloads feed to a temporary JSON file and sets the .fileName property for subsequent loading.

param	type	description
fileName?	`string`	Destination path (defaults to a generated temp path).
expansionMode?	UpdateFeedExpansionMode

Returns:

data table? — The expanded feed data, or nil on failure.
err string? — Error message on failure.

loadFile ¶

MoonScriptLua

updateFeed\loadFile srcPath, expansionMode

updateFeed:loadFile(srcPath, expansionMode)

Loads and parses a local feed JSON file, expanding all template variables in-place. Use this to load a feed already on disk without going through the network. Defaults to the .fileName property, which was either provided in the constructor, or set to a temporary path when the feed is fetched. was loaded from a URL; otherwise local, which resolves the rolling localFileBasePath template variables and exposes the localFilePath property on file records for build tooling such as the bundler.

param	type	description
srcPath?	`string`	Local filesystem path to the feed JSON file.
expansionMode?	UpdateFeedExpansionMode	Expansion mode. Defaults to remote if the feed

Returns:

data table? — The expanded feed data, or nil on failure.
err string? — Error message on failure.

ensureLoaded ¶

MoonScriptLua

updateFeed\ensureLoaded expansionMode

updateFeed:ensureLoaded(expansionMode)

Fetches the feed (or loads it from disk if local) in case it hasn't been loaded yet.

param	type	description
expansionMode?	UpdateFeedExpansionMode	The expansion mode required for the operation.

Returns:

feedData table? — The expanded feed data, or nil on failure.
err string? — An error message in case of failure.

expand ¶

MoonScriptLua

updateFeed\expand mode

updateFeed:expand(mode)

Expands and returns @data for the requested mode, rebuilt each call from a fresh deep copy of another consumer's expansion. The feed must be loaded (@unexpandedData set) first.

param	type	description
mode?	UpdateFeedExpansionMode	Expansion mode; local mode additionally resolves rolling templates for local source file paths.

Returns:

data table

getScript ¶

MoonScriptLua

updateFeed\getScript namespace, scriptType, config, autoChannel

updateFeed:getScript(namespace, scriptType, config, autoChannel)

Retrieves a script update record by namespace and type.

param	type	description
namespace	`string`
scriptType	ScriptType\|`boolean`	A ScriptType value (true/false accepted for legacy module/automation).
config?	`table`
autoChannel?	`boolean`	Select the default channel automatically.

Returns:

record ScriptUpdateRecord|boolean|nil — False when not found, nil on error.
err string?

getMacro ¶

MoonScriptLua

updateFeed\getMacro namespace, config, autoChannel

updateFeed:getMacro(namespace, config, autoChannel)

Retrieves an automation script update record by namespace.

param	type	description
namespace	`string`
config?	`table`
autoChannel?	`boolean`	Select the default channel automatically.

Returns:

record ScriptUpdateRecord|boolean|nil — False when not found, nil on error.
err string?

getModule ¶

MoonScriptLua

updateFeed\getModule namespace, config, autoChannel

updateFeed:getModule(namespace, config, autoChannel)

Retrieves a module update record by namespace.

param	type	description
namespace	`string`
config?	`table`
autoChannel?	`boolean`	Select the default channel automatically.

Returns:

record ScriptUpdateRecord|boolean|nil — False when not found, nil on error.
err string?

getModuleVersion ¶

MoonScriptLua

updateFeed\getModuleVersion namespace

updateFeed:getModuleVersion(namespace)

Returns the default channel's version for a module namespace, or nil. "Default" means the channel with default:true; falls back to the first channel found.

param	type	description
namespace	`string`

Returns:

version string?

getProviders ¶

MoonScriptLua

updateFeed\getProviders alias

updateFeed:getProviders(alias)

Returns the modules in this feed whose default channel provides the given name. Only the modules section is searched (automation scripts can't be required). The feed must be loaded.

param	type	description
alias	`string`	The required module name to find providers for.

Returns:

providers ScriptUpdateRecord[] — Update records (default channel selected) whose provides lists the name.

validateAgainstSchema ¶

MoonScriptLua

updateFeed\validateAgainstSchema schemaDir

updateFeed:validateAgainstSchema(schemaDir)

Validates @rawFeedData against the feed schema matching its declared format version. Best-effort: warns through @logger but never raises, so an unavailable schema rock or a non-conforming feed doesn't block an update.

param	type	description
schemaDir	`string`\|`string`[]	Directory holding the feed schemas (named `v<version>.json`).

Returns:

valid boolean? — Whether the feed is valid, or nil if validation couldn't be performed.
schemaVersion string? — The feed format version validated against, if any.
message string? — A success or error message.

updateFeed ¶

MoonScriptLua

updateFeed\updateFeed opts

updateFeed:updateFeed(opts)

Loads the feed (unless already loaded), optionally validates it, refreshes the targeted packages in place and writes the result back to disk. The feed path is the one supplied to the constructor; pre-load with loadFile() if you need to act on the feed before refresh.

param	type	description
opts?	`{ channel?: string, filter?: ScriptTargetFilter, schemaDir?: string\|string[], outPath?: string\|boolean, addFiles?: boolean, markReleased?: boolean\|string }`	Options. `outPath` false performs a dry run; nil/true defaults to the loaded feed's source path. `addFiles` appends entries (with computed SHA-1s) for on-disk files missing from the targeted channel; the added names are reported per package in `addedFiles`. `markReleased` stamps a release date on each targeted channel still marked unreleased — a date string sets that date, `true` uses today (UTC).

Returns:

stats { changed: integer, errored: integer, packages: table[] }|nil — Per-run statistics, or nil on a fatal load/write error.
err string?

mergeChannels ¶

MoonScriptLua

updateFeed\mergeChannels source, opts

updateFeed:mergeChannels(source, opts)

Copies channel data from another feed into this one, in place, and writes the result. For each package in the source, its from channel's raw data is copied into every to channel here, with each to channel's default flag set (true only for the given default channel) and its release date set when one is supplied. Channels not among to are left as they are, so they keep their previously published versions; a package missing here is added carrying only the to channels. Top-level feed metadata and each package's shared (non-channel) fields track the source. File hashes are copied verbatim — the from channel is assumed already in sync with its own source — so no files are read.

param	type	description
source	UpdateFeed	The loaded feed to copy channel data from.
opts	`{ from: string, to: string[], defaultChannel?: string, released?: string, outPath?: string\|boolean }`	`outPath` false does a dry run; nil/true writes to this feed's own path.

Returns:

merged string[]? — The namespaces whose channels were written, or nil on error.
err string?

bumpVersions ¶

MoonScriptLua

updateFeed\bumpVersions opts

updateFeed:bumpVersions(opts)

Bumps package versions on a channel to the repo's lockstep version: rewrites the marked version literal in each affected package's source, sets the channel's version, clears its release date, and refreshes its file hashes in place, then writes the feed. The target version is derived from the channel's release dates: a released highest version starts a new cycle (bumped by level); an unreleased one is joined, unless a bigger level reaches past it, carrying every package already bumped into that cycle up with it so a release never spans two versions. Bailing early if the feed's file hashes don't already match the sources keeps the version bump its only feed change.

param	type	description
opts	`{ channel?: string, level: SemverPrecision, namespaces?: string[], allChanged?: boolean, outPath?: string\|boolean }`	`namespaces` or `allChanged` selects what to bump; `outPath` false does a dry run.

Returns:

stats { channel: string, target: string, bumped: { namespace: string, from: string, to: string }[] }|nil
err string?

resolve ¶

MoonScriptLua

updateFeed\resolve opts

updateFeed:resolve(opts)

Expands every template variable in the feed to a concrete value and drops the template plumbing (fileBaseUrl(s), localFileBasePath(s), root vars), so a client whose feed templater predates those features reads it literally. File SHA-1s are carried over untouched — no local files are read.

param	type	description
opts?	`{ fileBaseUrl?: string, feedSchemaVersion?: string, outPath?: string\|false }`	`fileBaseUrl` overrides the download base before expansion, adding a trailing slash when missing; `feedSchemaVersion` stamps `dependencyControlFeedFormatVersion`; `outPath` is the destination (default `<feed>.resolved.json` beside the source), or false to return the resolved table without writing.

Returns:

result string|table|nil — The path written to, the resolved table when outPath is false, or nil on error.
err string? — Error message on failure, including a URL field that still carries an unexpanded variable.

formatReleaseNotes ¶

MoonScriptLua

updateFeed\formatReleaseNotes opts

updateFeed:formatReleaseNotes(opts)

Renders a GitHub-flavored markdown release body from one version's changelog across every package that has entries for it. Marker scopes become bold lead-ins; the package whose name matches the feed name is treated as primary, so its unscoped entries render with no lead-in, while other packages fall back to their namespace's last segment.

param	type	description
opts?	`{version?: string, channel?: string, title?: string}`	Give `version` directly, or a `channel` whose highest advertised version is used; with neither, the channel marked default: true. `title` adds a top-level heading.

Returns:

notes string? — The markdown body (empty string when no package has entries for the version), or nil on error.
error string?

deployFiles ¶

MoonScriptLua

updateFeed\deployFiles distDir, filter, clobber

updateFeed:deployFiles(distDir, filter, clobber)

Copies every file listed in the feed to distDir using the Updater's install layout. A file the feed marks for deletion (delete: true) is removed from distDir if present, rather than deployed. The feed must have been loaded with ExpansionMode.Local so localFileBasePath is populated.

param	type	description
distDir	`string`	Absolute path of the output dist directory.
filter?	ScriptTargetFilter	Restricts which packages are deployed (default: all).
clobber?	`boolean`	Overwrite existing destination files (default false).

Returns:

fileCount number — Number of files successfully copied.
errCount number — Number of files that failed to deploy — a missing source, a copy error, or a deletion that couldn't be performed.

findUnlistedFiles ¶

MoonScriptLua

updateFeed\findUnlistedFiles filter, channelName

updateFeed:findUnlistedFiles(filter, channelName)

Finds files present on disk that a package's targeted channel doesn't list, by inverting the channel's effective per-file-type local path templates. Only localFileBasePaths entries whose sole unexpanded variable is @{fileName} are scanned; a file matching several types is attributed to the one with the longest literal prefix. Loads the feed in local mode if needed.

param	type	description
filter?	ScriptTargetFilter	Restricts which packages are scanned (default: all).
channelName?	`string`	Channel whose file list is diffed (default: each package's default channel).

Returns:

unlisted {namespace: string, scriptType: ScriptType, channel: string, name: string, type?: string, url: string, localFilePath: string}[]? — Feed-ready entries for the discovered files, sorted by namespace, type, and name (empty when everything on disk is listed; nil on a load error).
err string? — Error message on failure.

walkPackages ¶

MoonScriptLua

updateFeed\walkPackages filter

updateFeed:walkPackages(filter)

Returns a coroutine-based iterator over the packages of this feed that pass the filter. The feed must have been loaded before calling this method. Each iteration yields three values: pkg – the package object; the package key is accessible via .namespace scriptType – the script type (ScriptType.Module / .Automation) section – the section name (e.g. "macros" or "modules")

param	type	description
filter?	ScriptTargetFilter	Restricts which packages are walked (default: all).

Returns:

iterator function

walkFiles ¶

MoonScriptLua

updateFeed\walkFiles filter

updateFeed:walkFiles(filter)

Returns a coroutine-based iterator over every file entry of the packages passing the filter. The feed must have been loaded before calling this method. Each iteration yields five values: file – the file object; .localFilePath resolves localFileBasePath+name against @feedDir channel – the channel object; the channel key is accessible via .name pkg – the package object; the package key is accessible via .namespace section – the section name (e.g. "macros" or "modules") scriptType – the script type (ScriptType.Module / .Automation)

param	type	description
filter?	ScriptTargetFilter	Restricts which packages are walked (default: all).

Returns:

iterator function

Class methods¶

getFileDeployPath ¶

MoonScriptLua

UpdateFeed\getFileDeployPath namespace, scriptType, fileName, fileType, rootDir

UpdateFeed:getFileDeployPath(namespace, scriptType, fileName, fileType, rootDir)

Resolves the install path of a packaged file from its owning script's namespace, mirroring the layout the Updater installs into: automation scripts go to the autoload dir, modules to the include dir (under their namespace path), and test files to the matching DepUnit test dir.

param	type	description
namespace	`string`
scriptType	ScriptType	A ScriptType value.
fileName	`string`	The file's feed name (e.g. ".moon", "/Common.moon").
fileType?	`string`	"script" or "test" (default "script").
rootDir?	`string`	The root directory for deployment.

Returns:

path string?
err string?

deserialize ¶

MoonScriptLua

UpdateFeed.deserialize content

UpdateFeed.deserialize(content)

Decodes a feed's JSON into its unexpanded working data — null sentinels stripped and the macros/modules/ knownFeeds sections ensured present — alongside the raw null-preserving decode kept for write-back. Shared by loadFile and the feed cache's L1 layer so both agree on the shape.

param	type	description
content	`string`	The raw feed JSON.

Returns:

unexpandedData table? — The working feed data, before template expansion (nil on a JSON parse error).
raw table? — The pristine decode with dkjson.null sentinels intact, for write-back.

Fields¶

field	type	description
url	`string`	This feed's source URL, or a file:// URL over its local file when it has no remote URL (read-only).
knownFeeds	`string`[]	URLs referenced in this feed's `knownFeeds` section; empty when the feed isn't loaded. Read-only.
feedDir?	`string`	Directory of the loaded feed file; local file paths resolve against it during local-mode expansion.
defaultConfig	`table`

Enums¶

UpdateFeedExpansionMode ¶

member	value	description
Remote	`"remote"`	Remote (default): expand `fileBaseUrl`/`url` to their download URLs.
Local	`"local"`	additionally resolve the `localFileBasePath`/`localFilePath` sister fields to on-disk paths (used by the bundler), leaving the remote fields intact.

Types¶

UpdateFeedChannelTemplateState ¶

The rolling-template values in effect at one channel, captured during local-mode expansion so the local path templates can be inverted for file discovery.

field	type	description
localFileBasePath?	`string`	Scalar local base path in effect.
localFileBasePaths?	`table<string, string>`	Per-file-type local path templates in effect.
fileBaseUrls?	`table<string, string>`	Per-file-type URL templates in effect.

UpdateFeedTemplateSpec ¶

Declares one template variable. A regular template captures its value at a fixed tree depth. A rolling template re-reads its key at every depth, so a value set at any level (feed root, section container, package, channel) rolls down until overridden.

field	type	description
depth?	`integer`	Tree depth the variable is captured at; absent for rolling templates.
order?	`integer`	Collection order among same-depth templates; a template's own key expansion can only reference lower-order variables of its depth.
key?	`string`	Field the value is read from on the visited object and written back to in expanded form.
parentKeys?	`table<string, boolean>`	Captures the visited object's own key as the value when the key of the object's parent container is in this set.
selfKeys?	`table<string, boolean>`	Captures the visited object's own key as the value when that key is in this set.
map?	`table<string, string>`	Translates a selfKeys-captured key into the variable value; without a matching entry the key itself is used.
repl?	`string`	Lua pattern replaced by `to` in the captured value.
to?	`string`	Replacement for `repl` matches.
rolling?	`boolean`	Marks a rolling template.
expansionModes?	`table<UpdateFeedExpansionMode, boolean>`	Expansion modes the template participates in; absent means all.
default?	`string`	Fallback value when no level of the feed sets the key.
keyBy?	`string`	Field of a record under `keyAt` whose value selects an entry of the rolling map (e.g. a file's `type`).
keyAt?	`string`	Container key whose records trigger the keyed collapse (e.g. "files").
keyDefault?	`string`	`keyBy` value assumed when the record lacks the field.
collapseInto?	`string`	Name of the scalar rolling template the selected map entry replaces; the scalar stays in place as the fallback when the map has no entry for the key.