smartFolder

The eagle.smartFolder API lets you create, query, modify, and delete smart folders.

Version Requirement: This feature requires Eagle 4.0 build22 or later.

// Create a smart folder using the fluent builder
const sf = await eagle.smartFolder.create({
    name: 'Large PNGs',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// Modify properties
sf.name = 'Extra Large PNGs';
sf.iconColor = 'blue';

// Save changes
await sf.save();

🦄 Best Practice: Use the getRules() method to get all available filter rule schemas. Combined with the rule() fluent builder and Condition.create() helper, you can construct conditions more safely.

Methods

create(options)

Create a smart folder

• options Object

  • name string - Smart folder name

  • conditions Object[] - Filter conditions

  • description string (optional) - Description

  • iconColor string (optional) - Icon color

  • parent string (optional) - Parent smart folder ID

• Returns Promise<smartFolder: SmartFolder> - The newly created smart folder

// Using raw JSON format
let sf = await eagle.smartFolder.create({
    name: 'Cat Images',
    conditions: [
        {
            rules: [
                { property: 'name', method: 'contain', value: 'cat' }
            ],
            match: 'AND'
        }
    ]
});

// Using the fluent builder
let sf2 = await eagle.smartFolder.create({
    name: 'Large Images',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('height')['>']([1080]),
        ])
    ],
    iconColor: 'blue'
});

---

get(options)

Get smart folders matching the specified criteria.

• options Object - Query criteria

  • id string (optional) - Smart folder ID

  • ids string[] (optional) - Array of smart folder IDs

• Returns Promise<smartFolders: SmartFolder[]> - Query results

// Get smart folders by IDs
let smartFolders = await eagle.smartFolder.get({
    ids: ['sf_id1', 'sf_id2']
});

---

getAll()

Get all smart folders.

• Returns Promise<smartFolders: SmartFolder[]> - Query results

let smartFolders = await eagle.smartFolder.getAll();

---

getById(smartFolderId)

Get the smart folder with the specified smartFolderId.

• smartFolderId string - Smart folder ID

• Returns Promise<smartFolder: SmartFolder> - Query result

let sf = await eagle.smartFolder.getById('smart_folder_id');

---

getByIds(smartFolderIds)

Get smart folders matching the specified smartFolderIds.

• smartFolderIds string[] - Array of smart folder IDs

• Returns Promise<smartFolders: SmartFolder[]> - Query results

let smartFolders = await eagle.smartFolder.getByIds(['sf_id1', 'sf_id2']);

---

remove(smartFolderId)

Delete the specified smart folder.

• smartFolderId string - Smart folder ID

• Returns Promise<result: boolean>

await eagle.smartFolder.remove('smart_folder_id');

---

getRules()

Get the available filter rule schema. Returns supported methods, valueType, options, and more for each property.

• Returns Promise<rules: Object> - Rule schema object

const rules = await eagle.smartFolder.getRules();
console.log(rules);
// {
//     name: { methods: ['contain', 'equal', ...], valueType: 'string' },
//     width: { methods: ['=', '>=', '>', ...], valueType: 'number' },
//     type: { methods: ['equal', 'unequal'], valueType: 'string', options: [...] },
//     ...
// }

Tip: Call getRules() first to get available properties and methods, then use the rule() builder to construct conditions safely.

---

rule(property)

Fluent builder for constructing a single filter rule. Returns an object with all available methods; calling a method produces the corresponding Rule object.

• property string - Filter property (e.g., name, width, type)

• Returns Object - Builder object with all available methods

// Name contains "cat"
eagle.smartFolder.rule('name').contain('cat');

// Width greater than 1920
eagle.smartFolder.rule('width')['>']([1920]);

// Type equals png
eagle.smartFolder.rule('type').equal('png');

// Rating greater than or equal to 3
eagle.smartFolder.rule('rating')['>=']([3]);

// Name is empty
eagle.smartFolder.rule('name').empty();

// Used with Condition.create
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);

---

Class: SmartFolder

The object type returned by SmartFolder API get methods, providing modify and save capabilities.

let sf = await eagle.smartFolder.getById('smart_folder_id');

console.log(sf.id);
console.log(sf.name);

sf.name = 'New Name';
console.log(sf.name);

await sf.save();

🦄 Best Practice: Use the SmartFolder instance's save() method to persist changes safely.

---

Instance Methods

save()

Save all modifications

• Returns Promise<smartFolder: SmartFolder> - The updated smart folder

let sf = await eagle.smartFolder.getById('smart_folder_id');
sf.name = 'New Name';
sf.iconColor = 'green';

// Save changes
await sf.save();

---

getItems(options)

Get items matching this smart folder's filter conditions.

• options Object (optional)

  • orderBy string (optional) - Sort field

  • fields string[] (optional) - Fields to return

• Returns Promise<items: Object[]> - Array of matching items

let sf = await eagle.smartFolder.getById('smart_folder_id');

// Get all matching items
let items = await sf.getItems();

// Specify return fields
let items2 = await sf.getItems({
    fields: ['id', 'name', 'ext', 'width', 'height']
});

---

Instance Properties

A SmartFolder instance contains the following properties:

id string

Read-only. Smart folder ID.

name string

Smart folder name.

conditions Object[]

Filter conditions array.

description string

Smart folder description.

icon string

Read-only. Smart folder icon.

iconColor string

Smart folder icon color.

let sf = await eagle.smartFolder.getById('smart_folder_id');

// Set icon color to red
sf.iconColor = eagle.smartFolder.IconColor.Red;

// Or use a string value directly
sf.iconColor = 'red';

// Save changes
await sf.save();

modificationTime integer

Read-only. Last modification timestamp.

children SmartFolder[]

Read-only. Array of child smart folders.

let children = sf.children;
console.log(children[0].name);

parent string

Read-only. Parent smart folder ID.

imageCount integer

Read-only. Number of items matching the conditions.

---

Helper Classes

SmartFolder.Rule

Rule object describing a single filter rule.

// Create via constructor
let rule = new eagle.smartFolder.Rule('name', 'contain', 'cat');

// Or use the rule() fluent builder (recommended)
let rule2 = eagle.smartFolder.rule('name').contain('cat');

SmartFolder.Condition

Condition group object containing multiple rules and logic operators.

// Create using Condition.create
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);

// Create an exclusion condition
let excludeCondition = eagle.smartFolder.Condition.create('OR', [
    eagle.smartFolder.rule('type').equal('gif'),
], 'FALSE');

Condition.create(match, rules, boolean)

• match string - 'AND' or 'OR'

• rules Object[] - Array of rules

• boolean string (optional) - 'TRUE' (include, default) or 'FALSE' (exclude)

---

Static Properties

IconColor Object

Provides predefined icon color constants for setting the iconColor property.

eagle.smartFolder.IconColor.Red      // 'red'
eagle.smartFolder.IconColor.Orange   // 'orange'
eagle.smartFolder.IconColor.Yellow   // 'yellow'
eagle.smartFolder.IconColor.Green    // 'green'
eagle.smartFolder.IconColor.Aqua     // 'aqua'
eagle.smartFolder.IconColor.Blue     // 'blue'
eagle.smartFolder.IconColor.Purple   // 'purple'
eagle.smartFolder.IconColor.Pink     // 'pink'

🦄 Best Practice: Use eagle.smartFolder.IconColor constants instead of string values directly for better code hints and type safety.