@ztimson/utils 0.18.2 → 0.19.1

package/dist/path-events.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Available methods:
+ * * - All/Wildcard
+ * n - None
+ * c - Create
+ * r - Read
+ * u - Update
+ * d - Delete
+ * x - Execute
+ */
+export type Method = '*' | 'n' | 'c' | 'r' | 'u' | 'd' | 'x';
+/**
+ * Shorthand for creating PathedEvent from a string
+ *
+ * @example
+ * ```ts
+ * const event: PathedEvent = PE`users/system:*`;
+ * ```
+ *
+ * @param {TemplateStringsArray} str String that will be parsed into PathedEvent
+ * @param {string} args
+ * @return {PathEvent} PathedEvent object
+ */
+export declare function PE(str: TemplateStringsArray, ...args: string[]): PathEvent;
+/**
+ * Shorthand for creating PathedEvent strings, ensures paths are correct
+ *
+ * @param {TemplateStringsArray} str
+ * @param {string} args
+ * @return {string}
+ * @constructor
+ */
+export declare function PES(str: TemplateStringsArray, ...args: any[]): string;
+/**
+ * A pathed event broken down into its core components for easy processing
+ * PathedEvent Structure: `module/path/name:property:method`
+ * Example: `users/system:crud` or `storage/some/path/file.txt:r`
+ */
+export declare class PathEvent {
+    /** First directory in path */
+    module: string;
+    /** Entire path, including the module & name */
+    fullPath: string;
+    /** Path including the name, excluding the module */
+    path: string;
+    /** Last sagment of path */
+    name: string;
+    /** List of methods */
+    methods: Method[];
+    /** All/Wildcard specified */
+    all: boolean;
+    /** None specified */
+    none: boolean;
+    /** Create method specified */
+    create: boolean;
+    /** Read method specified */
+    read: boolean;
+    /** Update method specified */
+    update: boolean;
+    /** Delete method specified */
+    delete: boolean;
+    constructor(pathedEvent: string | PathEvent);
+    /**
+     * Combine multiple pathed events into one parsed object. Longest path takes precedent, but all subsequent methods are
+     * combined until a "none" is reached
+     *
+     * @param {string | PathEvent} paths PathedEvents as strings or pre-parsed
+     * @return {PathEvent} Final combined permission
+     */
+    static combine(paths: (string | PathEvent)[]): PathEvent;
+    /**
+     * Squash 2 sets of paths & return true if any overlap is found
+     *
+     * @param {string | PathEvent | (string | PathEvent)[]} target Array of PathedEvents as strings or pre-parsed
+     * @param has Target must have at least one of these path
+     * @return {boolean} Whether there is any overlap
+     */
+    static has(target: string | PathEvent | (string | PathEvent)[], ...has: (string | PathEvent)[]): boolean;
+    /**
+     * Squash 2 sets of paths & return true if the target has all paths
+     *
+     * @param {string | PathEvent | (string | PathEvent)[]} target Array of PathedEvents as strings or pre-parsed
+     * @param has Target must have all these paths
+     * @return {boolean} Whether there is any overlap
+     */
+    static hasAll(target: string | PathEvent | (string | PathEvent)[], ...has: (string | PathEvent)[]): boolean;
+    /**
+     * Same as `has` but raises an error if there is no overlap
+     *
+     * @param {string | string[]} target Array of PathedEvents as strings or pre-parsed
+     * @param has Target must have at least one of these path
+     */
+    static hasFatal(target: string | PathEvent | (string | PathEvent)[], ...has: (string | PathEvent)[]): void;
+    /**
+     * Same as `hasAll` but raises an error if the target is missing any paths
+     *
+     * @param {string | string[]} target Array of PathedEvents as strings or pre-parsed
+     * @param has Target must have all these paths
+     */
+    static hasAllFatal(target: string | PathEvent | (string | PathEvent)[], ...has: (string | PathEvent)[]): void;
+    /**
+     * Create pathed event string from its components
+     *
+     * @param {string | string[]} path Event path
+     * @param {Method} methods Event method
+     * @return {string} String representation of PathedEvent
+     */
+    static toString(path: string | string[], methods: Method | Method[]): string;
+    /**
+     * Create pathed event string from its components
+     *
+     * @return {string} String representation of PathedEvent
+     */
+    toString(): string;
+}
+export type PathListener = (event: PathEvent, ...args: any[]) => any;
+export type PathUnsubscribe = () => void;
+export interface IPathedEventEmitter {
+    emit(event: string, ...args: any[]): void;
+    off(listener: PathListener): void;
+    on(event: string, listener: PathListener): PathUnsubscribe;
+    once(event: string, listener?: PathListener): Promise<any>;
+    relayEvents(emitter: PathEventEmitter): void;
+}
+/**
+ * Event emitter that uses paths allowing listeners to listen to different combinations of modules, paths & methods
+ */
+export declare class PathEventEmitter implements IPathedEventEmitter {
+    private listeners;
+    emit(event: string | PathEvent, ...args: any[]): void;
+    off(listener: PathListener): void;
+    on(event: string | string[], listener: PathListener): PathUnsubscribe;
+    once(event: string | string[], listener?: PathListener): Promise<any>;
+    relayEvents(emitter: IPathedEventEmitter): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.18.2",
+	"version": "0.19.1",
 	"description": "Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",