nav

type Acceleration struct {
	WgAn            boost.WaitGroupAn
	RoutineName     boost.GoRoutineName
	NoW             int
	JobsChOut       TraverseItemJobStream
	JobResultsCh    boost.JobOutputStream[TraverseOutput]
	OutputChTimeout time.Duration
}

type AccelerationOperators interface {
	Runnable
	NoW(now int) AccelerationOperators
	Consume(outputCh boost.JobOutputStream[TraverseOutput], timeout time.Duration) AccelerationOperators
}

type ActiveState struct {
	Root     string
	Listen   ListeningState
	NodePath string
	Depth    int
	Metrics  *MetricCollection
}

type AscendancyHandler func(item *TraverseItem)

type AsyncInfo struct {
	// this doesn't seem right, the client shouldn't have to specify
	// the routine name for the navigator; should be a readonly prop
	// of the navigator. Perhaps, it can be overridden by the user
	// here, but the navigator should have an internally defined default.
	//
	NavigatorRoutineName boost.GoRoutineName
	WaitAQ               boost.AnnotatedWgAQ

	// why are we passing in the jobs output channel here, rather than...
	// (perhaps a new operator, like how Consume() op takes the outputCh?)
	// The difference here though is that JobsChanOut is mandatory but
	// Consume & outputCh are optional.
	//
	JobsChanOut TraverseItemJobStream
}

type BeginHandler func(ns *NavigationState)

type CascadeBehaviour struct {
	// Depth sets a maximum traversal depth
	//
	Depth uint

	// NoRecurse is an alternative to using Depth, but limits the traversal
	// to just the path specified by the user. Since the raison d'etre
	// of the navigator is to recursively process a directory tree, using
	// NoRecurse would appear to be contrary to its natural behaviour. However
	// there are clear usage scenarios where a client needs to process
	// only the files in a specified directory.
	//
	NoRecurse bool
}

type CompoundExtendedGlobFilter struct {
	CompoundFilter
	// contains filtered or unexported fields
}

type CompoundFilter struct {
	Name    string
	Pattern string
	Negate  bool
}

type CompoundFilterDef struct {
	// Type specifies the type of filter (mandatory)
	Type FilterTypeEnum

	// Description describes filter (optional)
	Description string

	// Pattern filter definition (mandatory)
	Pattern string

	// Negate, reverses the applicability of the filter (Defaults to false)
	Negate bool

	// Custom client define-able filter. When restoring for resume feature,
	// its the client's responsibility to restore this themselves (see
	// PersistenceRestorer)
	Custom CompoundTraverseFilter `json:"-"`
}

type CompoundGlobFilter struct {
	CompoundFilter
}

type CompoundRegexFilter struct {
	CompoundFilter
	// contains filtered or unexported fields
}

type CompoundTraverseFilter interface {
	// Description describes filter
	Description() string

	// Validate ensures the filter definition is valid, panics when invalid
	Validate()

	// Source, filter definition (comes from filter definition Pattern)
	Source() string

	// Matching returns the collection of files contained within this
	// item's folder that matches this filter.
	Matching(children []fs.DirEntry) []fs.DirEntry
}

type CreateNewRunnerWith int

type DirectoryContents struct {
	Options *TraverseOptions
	Folders []fs.DirEntry
	Files   []fs.DirEntry
}

type DirectoryContentsOrderEnum uint

type EachDirectoryItemPredicate func(childItem *TraverseItem) bool

type EndHandler func(result *TraverseResult)

type EnoughAlready struct {
	Files   bool
	Folders bool
}

type EntryQuantities struct {
	Files   uint
	Folders uint
}

type ExtendHookFn func(navi *NavigationInfo, entries *DirectoryContents)

type ExtendedGlobFilter struct {
	Filter
	// contains filtered or unexported fields
}

type ExtendedItem struct {
	Depth     int               // traversal depth relative to the root
	IsLeaf    bool              // defines whether this node a leaf node
	Name      string            // derived as the leaf segment from filepath.Split
	Parent    string            // derived as the directory from filepath.Split
	SubPath   string            // represents the path between the root and the current item
	NodeScope FilterScopeBiEnum // type of folder corresponding to the Filter Scope
	Custom    any               // to be set and used by the client
}

type Filter struct {
	// contains filtered or unexported fields
}

type FilterDef struct {
	// Type specifies the type of filter (mandatory)
	Type FilterTypeEnum

	// Description describes filter (optional)
	Description string

	// Pattern filter definition (mandatory)
	Pattern string

	// Scope which file system entries this filter applies to (defaults
	// to ScopeAllEn)
	Scope FilterScopeBiEnum

	// Negate, reverses the applicability of the filter (Defaults to false)
	Negate bool

	// IfNotApplicable, when the filter does not apply to a directory entry,
	// this value determines whether the callback is invoked for this entry
	// or not (defaults to TriStateBoolTrueEn/true).
	IfNotApplicable TriStateBoolEnum

	// Custom client define-able filter. When restoring for resume feature,
	// its the client's responsibility to restore this themselves (see
	// PersistenceRestorer)
	Custom TraverseFilter `json:"-"`

	// Poly allows for the definition of a PolyFilter which contains separate
	// filters that target files and folders separately. If present, then
	// all other fields are redundant, since the filter definitions inside
	// Poly should be referred to instead.
	Poly *PolyFilterDef
}

type FilterDefinitions struct {
	// Node denotes the filter object that represents the current file system item
	// being visited.
	//
	Node FilterDef

	// Children denotes the compound filter that is applied to the direct descendants
	// of the current file system item being visited.
	//
	Children CompoundFilterDef
}

type FilterInitHookFn func(o *TraverseOptions, frame *navigationFrame)

type FilterScopeBiEnum uint32

type FilterTypeEnum uint

type FilteredInfo struct {
	Counts EntryQuantities
	Enough EnoughAlready
}

type GlobFilter struct {
	Filter
}

type LabelledTraverseCallback struct {
	Label string
	Fn    TraverseCallback
}

type ListenBehaviour struct {
	InclusiveStart bool
	InclusiveStop  bool
}

type ListenDefinitions struct {
	// Node denotes the filter object that represents the current file system item
	// being visited.
	//
	StartAt *FilterDef
	StopAt  *FilterDef
}

type ListenHandler func(description string)

type ListenTriggers struct {
	Start TraverseFilter
	Stop  TraverseFilter
}

type ListeningState uint

type LogRotationOptions struct {
	// MaxSizeInMb, max size of a log file, before it is re-cycled
	MaxSizeInMb int

	// MaxNoOfBackups, max number of legacy log files that can exist
	// before being deleted
	MaxNoOfBackups int

	// MaxAgeInDays, max no of days before old log file is deleted
	MaxAgeInDays int
}

type Metric struct {
	Name  string
	Count uint
}

type MetricCollection map[MetricEnum]*Metric

type MetricEnum uint

type MonitorOptions struct {
	Log *slog.Logger
}

type NavigationBehaviours struct {
	// SubPath, behaviours relating to handling of sub-path calculation
	//
	SubPath SubPathBehaviour

	// Sort, behaviours relating to sorting of a folder's directory entries.
	//
	Sort SortBehaviour

	// Listen, behaviours relating to listen functionality.
	//
	Listen ListenBehaviour

	// Cascade controls how deep to navigate
	//
	Cascade CascadeBehaviour
}

type NavigationFilters struct {
	// Node denotes the filter object that represents the Node file system item
	// being visited.
	//
	Node TraverseFilter

	// Children denotes the Compound filter that is applied to the direct descendants
	// of the current file system item being visited.
	//
	Children CompoundTraverseFilter
}

type NavigationInfo struct {
	Options *TraverseOptions
	Item    *TraverseItem
	// contains filtered or unexported fields
}

type NavigationMetrics struct {
	// contains filtered or unexported fields
}

type NavigationRunner interface {
	AccelerationOperators
	WithPool(ai *AsyncInfo) AccelerationOperators
	Save(path string) error
}

type NavigationState struct {
	Root    *utils.VarProp[string]
	Filters *NavigationFilters
	Logger  *slog.Logger
}

type NavigationSync interface {
	Run(callback sessionCallback, nc syncable, args ...any) (*TraverseResult, error)
}

type Notifications struct {
	// OnBegin invoked at beginning of traversal
	///
	OnBegin BeginHandler

	// OnEnd invoked at end of traversal
	//
	OnEnd EndHandler

	// OnDescend handler to invoke as a folder is descended (before children)
	//
	OnDescend AscendancyHandler

	// OnAscend handler to invoke as a folder is ascended (after children)
	OnAscend AscendancyHandler

	// OnStart handler invoked when start listening condition met if enabled
	//
	OnStart ListenHandler

	// OnStop handler invoked when finish listening condition met if enabled
	//
	OnStop ListenHandler
}

type OptionsStore struct {
	// Subscription defines which node types are visited
	//
	Subscription TraverseSubscription

	// Behaviours collection of behaviours that adjust the way navigation occurs,
	// that can be tweaked by the client.
	//
	Behaviours NavigationBehaviours

	// FilterDefs definitions of filters that restricts for which file system nodes the
	// Callback is invoked for.
	//
	FilterDefs *FilterDefinitions

	// ListenDefs definitions to define when listening starts and stops. Filters
	// can be used to define the Listeners.
	//
	ListenDefs ListenDefinitions

	// Sampling options
	//
	Sampling SamplingOptions
}

type PersistCompoundFilterDef struct {
	Description string
	Source      string
}

type PersistFilterDef struct {
	Description string
	Source      string
	Scope       FilterScopeBiEnum
}

type PersistFilters struct {
	Node     *PersistFilterDef
	Children *PersistCompoundFilterDef
}

type PersistOptions struct {
	Format PersistenceFormatEnum
}

type PersistenceFormatEnum uint

type PersistenceRestorer func(o *TraverseOptions, active *ActiveState)

type PolyFilter struct {
	// File is the filter that applies to a file. Note that the client does
	// not have to set the File scope as this is enforced automatically as
	// well as ensuring that the Folder scope has not been set. The client is
	// still free to set other scopes.
	File TraverseFilter

	// Folder is the filter that applies to a folder. Note that the client does
	// not have to set the Folder scope as this is enforced automatically as
	// well as ensuring that the File scope has not been set. The client is
	// still free to set other scopes.
	Folder TraverseFilter
}

type PolyFilterDef struct {
	File   FilterDef
	Folder FilterDef
}

type Primary struct {
	Path            string
	OptionFn        TraverseOptionFn
	ProvidedOptions *TraverseOptions
	// contains filtered or unexported fields
}

type Prime struct {
	Path            string
	OptionsFn       TraverseOptionFn
	ProvidedOptions *TraverseOptions
}

type QueryStatusHookFn func(path string) (fs.FileInfo, error)

type ReadDirectoryHookFn func(dirname string) ([]fs.DirEntry, error)

type RegexFilter struct {
	Filter
	// contains filtered or unexported fields
}

type Resume struct {
	RestorePath string
	Restorer    func(o *TraverseOptions, active *ActiveState)
	Strategy    ResumeStrategyEnum
	// contains filtered or unexported fields
}

type ResumeStrategyEnum uint

type Resumption struct {
	RestorePath string
	Restorer    PersistenceRestorer
	Strategy    ResumeStrategyEnum
}

type Runnable interface {
	Run(args ...any) (*TraverseResult, error)
}

type RunnerInfo struct {
	ResumeInfo       *Resumption
	PrimeInfo        *Prime
	AccelerationInfo *Acceleration
}

type SampleTypeEnum uint

type SamplerOptions struct {
	// Custom allows the client to customise how a directory's contents are sampled.
	// The default way to sample is either by slicing the directory's contents or
	// by using the filter to select either the first/last n entries (using the
	// SamplingOptions). If the client requires an alternative way of creating a
	// sample, eg to take all files greater than a certain size, then this
	// can be achieved by specifying Each and While inside Custom.
	Custom SamplingIteratorOptions
}

type SamplingIteratorOptions struct {
	// Each enables customisation of the sampling functionality, instead of using
	// the defined filter. A directory's contents is sampled according to this
	// function. The function receives the TraverseItem being considered and should
	// return true to include in the sample, false otherwise.
	Each EachDirectoryItemPredicate

	// While enables customisation of the sampling functionality, instead of using
	// the defined filter. The sampling loop will continue to run while this
	// condition is true. The predicate function should return false once condition
	// has been met to complete the sample. Of course, the loop will only run while
	// there are still remaining items to consider (ie there are no more entries
	// to consider for the current traverse item).
	While WhileDirectoryPredicate
}

type SamplingOptions struct {
	// SampleInReverse determines the direction of iteration for the sampling
	// operation
	SampleInReverse bool

	// SampleType the type of sampling to use
	SampleType SampleTypeEnum

	// NoOf specifies number of items required in each sample (only applies
	// when not using Custom iterator options)
	NoOf EntryQuantities
}

type Session interface {
	StartedAt() time.Time
	Elapsed() time.Duration
}

type SessionRunner interface {
	With(with CreateNewRunnerWith, info *RunnerInfo) NavigationRunner
	Primary(info *Prime) NavigationRunner
	Resume(info *Resumption) NavigationRunner
}

type SkipTraversal uint

type SortBehaviour struct {
	// case sensitive traversal order
	//
	IsCaseSensitive bool

	// DirectoryEntryOrder defines whether a folder's files or directories
	// should be navigated first.
	//
	DirectoryEntryOrder DirectoryContentsOrderEnum
}

type SortEntriesHookFn func(entries []fs.DirEntry, custom ...any) error

type SubPathBehaviour struct {
	KeepTrailingSep bool
}

type SubPathHookFn func(info *SubPathInfo) string

type SubPathInfo struct {
	Root      string
	Item      *TraverseItem
	Behaviour *SubPathBehaviour
}

type TraverseCallback func(item *TraverseItem) error

type TraverseFilter interface {
	// Description describes filter
	Description() string

	// Validate ensures the filter definition is valid, panics when invalid
	Validate()

	// Source, filter definition (comes from filter definition Pattern)
	Source() string

	// IsMatch does this item match the filter
	IsMatch(item *TraverseItem) bool

	// IsApplicable is this filter applicable to this item's scope
	IsApplicable(item *TraverseItem) bool

	// Scope, what items this filter applies to
	Scope() FilterScopeBiEnum
}

type TraverseHooks struct {
	QueryStatus   QueryStatusHookFn
	ReadDirectory ReadDirectoryHookFn
	FolderSubPath SubPathHookFn
	FileSubPath   SubPathHookFn
	InitFilters   FilterInitHookFn
	Sort          SortEntriesHookFn
	Extend        ExtendHookFn
}

type TraverseItem struct {
	Path      string
	Entry     fs.DirEntry  // contains a FileInfo via Info() function
	Info      fs.FileInfo  // optional file info instance
	Extension ExtendedItem // extended information about the file system node, if requested
	Error     error
	Children  []fs.DirEntry

	Parent *TraverseItem
	// contains filtered or unexported fields
}

type TraverseItemInput struct {
	Item  *TraverseItem
	Label string
	Fn    TraverseCallback
}

type TraverseItemJob = boost.Job[TraverseItemInput]

type TraverseItemJobStream = boost.JobStream[TraverseItemInput]

type TraverseItemJobStreamR = boost.JobStreamR[TraverseItemInput]

type TraverseItemJobStreamW = boost.JobStreamW[TraverseItemInput]

type TraverseItemOutput = boost.JobOutput[TraverseOutput]

type TraverseItemOutputStream = boost.JobOutputStream[TraverseOutput]

type TraverseItemOutputStreamR = boost.JobOutputStreamR[TraverseOutput]

type TraverseItemOutputStreamW = boost.JobOutputStreamW[TraverseOutput]

type TraverseNavigator interface {
	// contains filtered or unexported methods
}

type TraverseOptionFn func(o *TraverseOptions)

type TraverseOptions struct {
	Store OptionsStore

	// Callback function to invoke for every item visited in the file system.
	//
	Callback *LabelledTraverseCallback `json:"-"`

	// Notify collection of notification function.
	//
	Notify Notifications `json:"-"`

	// TraverseHooks collection of hook functions, that can be overridden.
	//
	Hooks TraverseHooks `json:"-"`

	// Persist contains options for persisting traverse options
	//
	Persist PersistOptions `json:"-"`

	// Sampler defines options for sampling directory entries. There are
	// multiple ways of performing sampling. The client can either:
	// A) Use one of the four predefined functions see (SamplerOptions.Fn)
	// B) Use a Custom iterator. When setting the Custom iterator properties
	//
	Sampler SamplerOptions `json:"-"`

	// Monitor contains externally provided logger
	//
	Monitor MonitorOptions `json:"-"`
}

type TraverseOutput struct {
	Item  *TraverseItem
	Error error
}

type TraverseResult struct {
	Session Session
	Metrics *NavigationMetrics
	// contains filtered or unexported fields
}

type TraverseSession interface {
	Session

	Save(path string) error
	// contains filtered or unexported methods
}

type TraverseSubscription uint

type TriStateBoolEnum uint

type WhileDirectoryPredicate func(fi *FilteredInfo) bool