# smartFolder

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build22 or later.
{% endhint %}

```javascript
// 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();
```

{% hint style="success" %}
**🦄 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.
{% endhint %}

## Methods <a href="#methods" id="methods"></a>

## create(options) <a href="#create" id="create"></a>

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

```javascript
// 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) <a href="#get" id="get"></a>

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

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

***

## getAll() <a href="#getall" id="getall"></a>

Get all smart folders.

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

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

***

## getById(smartFolderId) <a href="#getbyid" id="getbyid"></a>

Get the smart folder with the specified `smartFolderId`.

* `smartFolderId` string - Smart folder ID
* Returns `Promise<smartFolder: SmartFolder>` - Query result

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

***

## getByIds(smartFolderIds) <a href="#getbyids" id="getbyids"></a>

Get smart folders matching the specified `smartFolderIds`.

* `smartFolderIds` string\[] - Array of smart folder IDs
* Returns `Promise<smartFolders: SmartFolder[]>` - Query results

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

***

## remove(smartFolderId) <a href="#remove" id="remove"></a>

Delete the specified smart folder.

* `smartFolderId` string - Smart folder ID
* Returns `Promise<result: boolean>`

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

***

## getRules() <a href="#getrules" id="getrules"></a>

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

* Returns `Promise<rules: Object>` - Rule schema object

```javascript
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: [...] },
//     ...
// }
```

{% hint style="info" %}
Tip: Call `getRules()` first to get available properties and methods, then use the `rule()` builder to construct conditions safely.
{% endhint %}

***

## rule(property) <a href="#rule" id="rule"></a>

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

```javascript
// 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 <a href="#class" id="class"></a>

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

```javascript
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();
```

{% hint style="success" %}
**🦄 Best Practice:** Use the SmartFolder instance's `save()` method to persist changes safely.
{% endhint %}

***

#### Instance Methods <a href="#instance-methods" id="instance-methods"></a>

### **save()**

Save all modifications

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

```javascript
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

```javascript
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 href="#instance-properties" id="instance-properties"></a>

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.

```javascript
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.

```javascript
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 <a href="#helpers" id="helpers"></a>

### **SmartFolder.Rule**

Rule object describing a single filter rule.

```javascript
// 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.

```javascript
// 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 <a href="#static-properties" id="static-properties"></a>

### **`IconColor` Object**

Provides predefined icon color constants for setting the `iconColor` property.

```javascript
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'
```

{% hint style="success" %}
**🦄 Best Practice:** Use `eagle.smartFolder.IconColor` constants instead of string values directly for better code hints and type safety.
{% endhint %}