@sketch-hq/sketch-assistant-types
Advanced tools
Comparing version 4.0.1-next.8 to 5.0.0-next.11
# @sketch-hq/sketch-assistant-types | ||
## 5.0.0-next.11 | ||
### Major Changes | ||
- 6733a97: Numerous refactors around Sketch file object iteration. | ||
## 4.0.1-next.8 | ||
### Patch Changes | ||
- bc13811: Initial release in monorepo. |
@@ -13,6 +13,2 @@ import { FileFormat3 } from '@sketch-hq/sketch-file-format-ts'; | ||
/** | ||
* All possible string values for the `_class` property in Sketch files. | ||
*/ | ||
export declare type SketchClass = FileFormat3.AnyObject['_class']; | ||
/** | ||
* Utility function for gathering metadata about Sketch file images. Is isomorphic in the sense that | ||
@@ -31,10 +27,2 @@ * its signature shouldn’t change across platforms. | ||
/** | ||
* Represents a Sketch file that is on disk. Collates the filepath with an object | ||
* typed as Contents from the file format. | ||
*/ | ||
export declare type SketchFile = { | ||
filepath: string; | ||
contents: FileFormat3.Contents; | ||
}; | ||
/** | ||
* Value or arbitrarily nested array of values. | ||
@@ -56,50 +44,78 @@ */ | ||
/** | ||
* Union of all possible objects with a `_class` value that can be found in a Sketch | ||
* file, injected with a JSON Pointer during file processing. | ||
* Unwrap an array type up one level, e.g. extract Foo from Foo[]. | ||
*/ | ||
export declare type Node<T = FileFormat3.AnyObject> = T & { | ||
$pointer: string; | ||
export declare type Unarray<T> = T extends Array<infer U> ? U : T; | ||
/** | ||
* Iterable object that uses a generator function. | ||
*/ | ||
export declare type GeneratorIterable<T> = { | ||
[Symbol.iterator]: () => Generator<T>; | ||
}; | ||
/** | ||
* Array of Nodes. A concrete example of this in a Sketch file is a group’s `layers` array. | ||
* A simple primitive type alias to represent a JSON Pointer string. | ||
*/ | ||
export interface NodeArray extends Array<Node> { | ||
$pointer: string; | ||
} | ||
export declare type JsonPointer = string; | ||
/** | ||
* All possible Node and primitive values that a JSON Pointer can resolve to in a Sketch file. | ||
* Represents a Sketch file that is on disk. Collates the filepath with an object typed as Contents | ||
* from the file format. | ||
*/ | ||
export declare type PointerValue = Node | NodeArray | Node<FileFormat3.Contents> | Node<FileFormat3.Contents['document']> | Node<FileFormat3.Contents['meta']> | Node<FileFormat3.Contents['user']> | string | number | boolean; | ||
export declare type SketchFile = { | ||
filepath: string; | ||
contents: FileFormat3.Contents; | ||
}; | ||
/** | ||
* Rule-supplied function called during cache iteration. Rules will typically use these while | ||
* scanning a Sketch file for relevant objects and checking the values against their logic. | ||
* The root document object with `_class` `document` in a parsed Sketch file. | ||
*/ | ||
export declare type NodeCacheVisitor = (data: Node) => Promise<void>; | ||
export declare type DocumentObject = FileFormat3.Contents['document']; | ||
/** | ||
* Rules supply a cache iterator config to register visitor functions against the specific object | ||
* types available in the cache. | ||
* Union of all possible objects in a parsed Sketch file that have a `_class` property, including | ||
* the root document object. | ||
*/ | ||
export declare type NodeCacheIteratorConfig = { | ||
[key in keyof NodeCache]?: NodeCacheVisitor; | ||
}; | ||
export declare type SketchFileObject = FileFormat3.AnyObject | DocumentObject; | ||
/** | ||
* A function that iterates a cache using a cache iteration config. | ||
* Look-up a pointer value using a Sketch file object reference. | ||
*/ | ||
export declare type NodeCacheIterator = (config: NodeCacheIteratorConfig) => Promise<void>; | ||
export declare type PointerMap = WeakMap<SketchFileObject, JsonPointer>; | ||
/** | ||
* A cache of Sketch file Nodes keyed by `_class` values. The special `$layers` key collates all | ||
* layer Nodes, and the `$groups` key collates all layer Nodes that are also groups. | ||
* A cache of Sketch file objects. Each key is a `_class` value from the file | ||
* format, and the corresponding value is an array of file objects with matching | ||
* `_class` values. | ||
*/ | ||
export declare type NodeCache = { | ||
$layers: Node[]; | ||
$groups: Node[]; | ||
export declare type ObjectCache = { | ||
[key in keyof FileFormat3.ClassMap]: FileFormat3.ClassMap[key][]; | ||
} & { | ||
[key in SketchClass]?: Node[]; | ||
anyGroup: FileFormat3.AnyGroup[]; | ||
anyLayer: FileFormat3.AnyLayer[]; | ||
document: DocumentObject[]; | ||
}; | ||
/** | ||
* A processed Sketch file is one that has had its objects cached into a NodeCache, and JSON | ||
* Pointers injected. | ||
* Same as ObjectCache, except the cache values are an iterable that yields | ||
* the file objects, rather than a simple array. | ||
*/ | ||
export declare type IterableObjectCache = { | ||
[key in keyof ObjectCache]: GeneratorIterable<Unarray<ObjectCache[key]>>; | ||
}; | ||
/** | ||
* Intersection of a Sketch file object and a pointer string. | ||
*/ | ||
/** | ||
* A processed Sketch file collates a SketchFile object along with various data structures suited | ||
* for efficiently inspecting its contents. | ||
*/ | ||
export declare type ProcessedSketchFile = { | ||
cache: NodeCache; | ||
/** | ||
* A cache of all local objects in the file, i.e. objects native to the file, not from a library. | ||
*/ | ||
objects: ObjectCache; | ||
/** | ||
* A cache of all foreign objects in the file, i.e. objects or children of objects from libraries. | ||
*/ | ||
foreignObjects: ObjectCache; | ||
/** | ||
* A map of file object references to JSON Pointer strings. | ||
*/ | ||
pointers: PointerMap; | ||
/** | ||
* The SketchFile that was processed. | ||
*/ | ||
file: SketchFile; | ||
@@ -174,7 +190,2 @@ }; | ||
/** | ||
* A function that when invoked repeatedly calls its callback for each of a Node’s parents | ||
* until it reaches the document root, at which point it stops. | ||
*/ | ||
export declare type ParentIterator = (node: Maybe<PointerValue>, callback: (target: Node | NodeArray | Node<FileFormat3.Contents['document']>) => void) => void; | ||
/** | ||
* Object containing utilities passed into rule functions. Where needed the util functions are | ||
@@ -190,14 +201,16 @@ * scoped to the current rule, e.g. `report` reports a violation for the current rule and | ||
/** | ||
* Iterate the Sketch file object cache. | ||
* Contains an iterator for each type of object in the Sketch file. | ||
*/ | ||
iterateCache: (config: NodeCacheIteratorConfig) => Promise<void>; | ||
objects: IterableObjectCache; | ||
/** | ||
* Iterate back through the Node’s parents to the Sketch file root. | ||
* Contains an iterator for each type of object in the Sketch file, filtered so it contains _only_ | ||
* foreign objects, that is, objects that have been imported from a library. | ||
*/ | ||
iterateParents: ParentIterator; | ||
foreignObjects: IterableObjectCache; | ||
/** | ||
* Get a rule option value by name. Throws if the rule hasn’t been configured in the assistant. | ||
* It’s essential that every rule activated in an assistant is properly configured. | ||
* Get a rule option value by name. Should throw if the rule hasn’t been configured properly in | ||
* the current assistant context, since it’s essential that every rule activated in an assistant is | ||
* fully configured. | ||
*/ | ||
getOption: (option: string) => Maybe<RuleOption>; | ||
getOption: <T = unknown>(option: string) => T; | ||
/** | ||
@@ -208,6 +221,2 @@ * Returns metadata for a given Sketch file image. | ||
/** | ||
* Converts a Node to the original file format type. | ||
*/ | ||
nodeToObject: <T extends FileFormat3.AnyObject>(node: Node) => T; | ||
/** | ||
* Return the md5 hash of an object. Keys are deeply sorted for a stable hash. | ||
@@ -224,10 +233,18 @@ * Useful for comparing deep similarity of Sketch document objects. By default | ||
/** | ||
* Resolve a JSON Pointer to a document object. | ||
* Resolve a JSON Pointer string to the value in the Sketch file it points to. | ||
*/ | ||
get: (pointer: string) => Maybe<PointerValue>; | ||
evalPointer: (pointer: JsonPointer) => unknown; | ||
/** | ||
* Resolve a JSON Pointer to a document object’s parent. | ||
* Determine the JSON Pointer for a given object in a Sketch file. | ||
*/ | ||
parent: (pointer: string) => Maybe<PointerValue>; | ||
getObjectPointer: (object: SketchFileObject) => JsonPointer | undefined; | ||
/** | ||
* Returns the immediate parent object of a Sketch file object. | ||
*/ | ||
getObjectParent: (object: SketchFileObject) => unknown; | ||
/** | ||
* Returns an array of parent objects for a given Sketch file object, all the way to the root. | ||
*/ | ||
getObjectParents: (object: SketchFileObject) => unknown[]; | ||
/** | ||
* Compares two style objects for equality. | ||
@@ -254,3 +271,3 @@ */ | ||
message: string; | ||
node?: Node; | ||
object?: SketchFileObject; | ||
}; | ||
@@ -327,3 +344,3 @@ /** | ||
/** | ||
* Assistant icon/image for display in Sketch. Should be a fully qualified uri to a publically | ||
* Assistant icon/image for display in Sketch. Should be a fully qualified uri to a publicly | ||
* hosted image file. | ||
@@ -357,3 +374,3 @@ */ | ||
* assistant’s content. Its exact value is not guaranteed, so an appropriate fallback locale should | ||
* always be used for unrecognised values. For assistants running in Sketch it’s value is likely | ||
* always be used for unrecognized values. For assistants running in Sketch it’s value is likely | ||
* to be either `en` or `zh-Hans`. | ||
@@ -414,3 +431,3 @@ */ | ||
* Human readable title for the rule. Can either be a string e.g. "Groups should not be empty", or | ||
* a function that returns a string, whicg enables the title to interpolate configuration values | ||
* a function that returns a string, which enables the title to interpolate configuration values | ||
* e.g. "Maximum height is 44px". | ||
@@ -417,0 +434,0 @@ */ |
{ | ||
"name": "@sketch-hq/sketch-assistant-types", | ||
"version": "4.0.1-next.8", | ||
"version": "5.0.0-next.11", | ||
"main": "dist/types", | ||
@@ -23,5 +23,5 @@ "types": "dist/types", | ||
"@schemastore/package": "0.0.5", | ||
"@sketch-hq/sketch-file-format-ts": "4.0.3", | ||
"@sketch-hq/sketch-file-format-ts": "5.0.0", | ||
"@types/json-schema": "7.0.4" | ||
} | ||
} |
Sorry, the diff of this file is not supported yet
33358
632
+ Added@sketch-hq/sketch-file-format-ts@5.0.0(transitive)
- Removed@sketch-hq/sketch-file-format-ts@4.0.3(transitive)