@kuralle-agents/fs 0.6.0

package/dist/encoding.js

@@ -0,0 +1,73 @@
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+export function toBuffer(content, encoding) {
+    if (content instanceof Uint8Array) {
+        return content;
+    }
+    if (encoding === 'base64') {
+        return Uint8Array.from(atob(content), (c) => c.charCodeAt(0));
+    }
+    if (encoding === 'hex') {
+        const bytes = new Uint8Array(content.length / 2);
+        for (let i = 0; i < content.length; i += 2) {
+            bytes[i / 2] = parseInt(content.slice(i, i + 2), 16);
+        }
+        return bytes;
+    }
+    if (encoding === 'binary' || encoding === 'latin1') {
+        const chunkSize = 65536;
+        if (content.length <= chunkSize) {
+            return Uint8Array.from(content, (c) => c.charCodeAt(0));
+        }
+        const result = new Uint8Array(content.length);
+        for (let i = 0; i < content.length; i++) {
+            result[i] = content.charCodeAt(i);
+        }
+        return result;
+    }
+    return textEncoder.encode(content);
+}
+export function fromBuffer(buffer, encoding) {
+    if (encoding === 'base64') {
+        if (typeof Buffer !== 'undefined') {
+            return Buffer.from(buffer).toString('base64');
+        }
+        const chunkSize = 65536;
+        let binary = '';
+        for (let i = 0; i < buffer.length; i += chunkSize) {
+            const chunk = buffer.subarray(i, i + chunkSize);
+            binary += String.fromCharCode(...chunk);
+        }
+        return btoa(binary);
+    }
+    if (encoding === 'hex') {
+        return Array.from(buffer)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    if (encoding === 'binary' || encoding === 'latin1') {
+        if (typeof Buffer !== 'undefined') {
+            return Buffer.from(buffer).toString(encoding);
+        }
+        const chunkSize = 65536;
+        if (buffer.length <= chunkSize) {
+            return String.fromCharCode(...buffer);
+        }
+        let result = '';
+        for (let i = 0; i < buffer.length; i += chunkSize) {
+            const chunk = buffer.subarray(i, i + chunkSize);
+            result += String.fromCharCode(...chunk);
+        }
+        return result;
+    }
+    return textDecoder.decode(buffer);
+}
+export function getEncoding(options) {
+    if (options === null || options === undefined) {
+        return undefined;
+    }
+    if (typeof options === 'string') {
+        return options;
+    }
+    return options.encoding ?? undefined;
+}

package/dist/in-memory-fs.d.ts

@@ -0,0 +1,48 @@
+import type { BufferEncoding, CpOptions, FileContent, FileSystem, FileSystemDirent, FsStat, InitialFiles, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from '@kuralle-agents/core';
+export type { FileContent, FsStat, FileSystem };
+export interface FsData {
+    [path: string]: import('@kuralle-agents/core').FsEntry;
+}
+export declare class InMemoryFs implements FileSystem {
+    private tree;
+    constructor(initialFiles?: InitialFiles);
+    writeFileSync(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding, metadata?: {
+        mode?: number;
+        mtime?: Date;
+    }): void;
+    writeFileLazy(path: string, lazy: () => string | Uint8Array | Promise<string | Uint8Array>, metadata?: {
+        mode?: number;
+        mtime?: Date;
+    }): void;
+    mkdirSync(path: string, options?: MkdirOptions): void;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBytes(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    writeFileBytes(path: string, content: Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<FileSystemDirent[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    glob(pattern: string): Promise<string[]>;
+    private resolveNode;
+    private locate;
+    private canonicalize;
+    private insertContent;
+    private insertLazy;
+    private forceLazy;
+    private scaffold;
+    private placeNode;
+    private deepClone;
+    private gather;
+    private missing;
+}

package/dist/in-memory-fs.js

@@ -0,0 +1,523 @@
+import { fromBuffer, getEncoding, toBuffer } from './encoding.js';
+import { createGlobMatcher, sortPaths, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, MAX_SYMLINK_DEPTH, normalizePath, resolvePath, SYMLINK_MODE, validatePath, } from './path-utils.js';
+const utf8 = new TextEncoder();
+function split(normalized) {
+    return normalized === '/' ? [] : normalized.slice(1).split('/');
+}
+function freshDir() {
+    return {
+        kind: 'dir',
+        children: new Map(),
+        mode: DEFAULT_DIR_MODE,
+        mtime: new Date(),
+    };
+}
+function kindToType(entry) {
+    if (entry.kind === 'file' || entry.kind === 'lazy')
+        return 'file';
+    if (entry.kind === 'dir')
+        return 'directory';
+    return 'symlink';
+}
+function nodeSize(entry) {
+    if (entry.kind === 'file')
+        return entry.bytes.length;
+    if (entry.kind === 'symlink')
+        return entry.target.length;
+    return 0;
+}
+function isInitObj(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        !(v instanceof Uint8Array) &&
+        'content' in v);
+}
+export class InMemoryFs {
+    tree;
+    constructor(initialFiles) {
+        this.tree = freshDir();
+        if (!initialFiles)
+            return;
+        for (const [p, v] of Object.entries(initialFiles)) {
+            if (typeof v === 'function') {
+                this.insertLazy(p, v);
+            }
+            else if (isInitObj(v)) {
+                this.insertContent(p, v.content, getEncoding(undefined), v.mode, v.mtime);
+            }
+            else {
+                this.insertContent(p, v);
+            }
+        }
+    }
+    writeFileSync(path, content, options, metadata) {
+        this.insertContent(path, content, getEncoding(options), metadata?.mode, metadata?.mtime);
+    }
+    writeFileLazy(path, lazy, metadata) {
+        this.insertLazy(path, lazy, metadata?.mode, metadata?.mtime);
+    }
+    mkdirSync(path, options) {
+        validatePath(path, 'mkdir');
+        const norm = normalizePath(path);
+        if (norm === '/') {
+            if (!options?.recursive) {
+                throw new Error(`EEXIST: directory already exists, mkdir '${path}'`);
+            }
+            return;
+        }
+        const segs = split(norm);
+        let dir = this.tree;
+        for (let i = 0; i < segs.length; i++) {
+            const last = i === segs.length - 1;
+            const child = dir.children.get(segs[i]);
+            if (child) {
+                if (child.kind === 'dir') {
+                    if (last) {
+                        if (!options?.recursive) {
+                            throw new Error(`EEXIST: directory already exists, mkdir '${path}'`);
+                        }
+                        return;
+                    }
+                    dir = child;
+                }
+                else if (last) {
+                    throw new Error(`EEXIST: file already exists, mkdir '${path}'`);
+                }
+                else if (options?.recursive) {
+                    const d = freshDir();
+                    dir.children.set(segs[i], d);
+                    dir = d;
+                }
+                else {
+                    throw new Error(`ENOENT: no such file or directory, mkdir '${path}'`);
+                }
+            }
+            else if (last) {
+                dir.children.set(segs[i], freshDir());
+            }
+            else if (options?.recursive) {
+                const d = freshDir();
+                dir.children.set(segs[i], d);
+                dir = d;
+            }
+            else {
+                throw new Error(`ENOENT: no such file or directory, mkdir '${path}'`);
+            }
+        }
+    }
+    async readFile(path, options) {
+        return fromBuffer(await this.readFileBytes(path), getEncoding(options));
+    }
+    async readFileBytes(path) {
+        validatePath(path, 'open');
+        if (normalizePath(path) === '/') {
+            throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+        }
+        const loc = this.locate(path, true, 'open');
+        if (!loc)
+            throw this.missing('open', path);
+        if (loc.entry.kind === 'dir' || loc.entry.kind === 'symlink') {
+            throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+        }
+        if (loc.entry.kind === 'lazy')
+            return this.forceLazy(loc);
+        return loc.entry.bytes;
+    }
+    async writeFile(path, content, options) {
+        this.insertContent(path, content, getEncoding(options));
+    }
+    async writeFileBytes(path, content) {
+        this.insertContent(path, content);
+    }
+    async appendFile(path, content) {
+        validatePath(path, 'append');
+        const extra = typeof content === 'string' ? utf8.encode(content) : content;
+        const loc = this.locate(path, true, 'append');
+        if (loc?.entry.kind === 'dir') {
+            throw new Error(`EISDIR: illegal operation on a directory, write '${path}'`);
+        }
+        if (!loc) {
+            this.insertContent(path, content);
+            return;
+        }
+        let existing;
+        if (loc.entry.kind === 'lazy') {
+            existing = await this.forceLazy(loc);
+        }
+        else if (loc.entry.kind === 'file') {
+            existing = loc.entry.bytes;
+        }
+        else {
+            this.insertContent(path, content);
+            return;
+        }
+        const merged = new Uint8Array(existing.length + extra.length);
+        merged.set(existing);
+        merged.set(extra, existing.length);
+        const fresh = loc.parent.children.get(loc.key);
+        if (fresh && fresh.kind === 'file') {
+            fresh.bytes = merged;
+            fresh.mtime = new Date();
+        }
+    }
+    async exists(path) {
+        if (path.includes('\0'))
+            return false;
+        try {
+            if (normalizePath(path) === '/')
+                return true;
+            return this.locate(path, true, 'access') !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    async stat(path) {
+        validatePath(path, 'stat');
+        if (normalizePath(path) === '/') {
+            return {
+                type: 'directory',
+                size: 0,
+                mtime: this.tree.mtime,
+                mode: this.tree.mode,
+            };
+        }
+        const loc = this.locate(path, true, 'stat');
+        if (!loc)
+            throw this.missing('stat', path);
+        if (loc.entry.kind === 'lazy')
+            await this.forceLazy(loc);
+        const n = loc.parent.children.get(loc.key);
+        if (!n)
+            throw this.missing('stat', path);
+        return {
+            type: kindToType(n),
+            size: nodeSize(n),
+            mtime: n.mtime,
+            mode: n.mode,
+        };
+    }
+    async lstat(path) {
+        validatePath(path, 'lstat');
+        if (normalizePath(path) === '/') {
+            return {
+                type: 'directory',
+                size: 0,
+                mtime: this.tree.mtime,
+                mode: this.tree.mode,
+            };
+        }
+        const loc = this.locate(path, false, 'lstat');
+        if (!loc)
+            throw this.missing('lstat', path);
+        if (loc.entry.kind === 'symlink') {
+            return {
+                type: 'symlink',
+                size: loc.entry.target.length,
+                mtime: loc.entry.mtime,
+                mode: loc.entry.mode,
+            };
+        }
+        if (loc.entry.kind === 'lazy')
+            await this.forceLazy(loc);
+        const n = loc.parent.children.get(loc.key);
+        if (!n)
+            throw this.missing('lstat', path);
+        return {
+            type: kindToType(n),
+            size: nodeSize(n),
+            mtime: n.mtime,
+            mode: n.mode,
+        };
+    }
+    async mkdir(path, options) {
+        this.mkdirSync(path, options);
+    }
+    async readdir(path) {
+        return (await this.readdirWithFileTypes(path)).map((d) => d.name);
+    }
+    async readdirWithFileTypes(path) {
+        validatePath(path, 'scandir');
+        const dir = this.resolveNode(path, true, 'scandir');
+        if (!dir)
+            throw this.missing('scandir', path);
+        if (dir.kind !== 'dir') {
+            throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+        }
+        const out = [];
+        for (const [name, child] of dir.children) {
+            out.push({ name, type: kindToType(child) });
+        }
+        return out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    async rm(path, options) {
+        validatePath(path, 'rm');
+        const segs = split(normalizePath(path));
+        if (segs.length === 0) {
+            if (options?.force)
+                return;
+            throw new Error(`EPERM: cannot remove root, rm '${path}'`);
+        }
+        let dir = this.tree;
+        for (let i = 0; i < segs.length - 1; i++) {
+            const next = dir.children.get(segs[i]);
+            if (!next || next.kind !== 'dir') {
+                if (options?.force)
+                    return;
+                throw this.missing('rm', path);
+            }
+            dir = next;
+        }
+        const name = segs[segs.length - 1];
+        const target = dir.children.get(name);
+        if (!target) {
+            if (options?.force)
+                return;
+            throw this.missing('rm', path);
+        }
+        if (target.kind === 'dir' &&
+            target.children.size > 0 &&
+            !options?.recursive) {
+            throw new Error(`ENOTEMPTY: directory not empty, rm '${path}'`);
+        }
+        dir.children.delete(name);
+    }
+    async cp(src, dest, options) {
+        validatePath(src, 'cp');
+        validatePath(dest, 'cp');
+        const srcNode = this.resolveNode(src, false, 'cp');
+        if (!srcNode)
+            throw this.missing('cp', src);
+        if (srcNode.kind === 'dir' && !options?.recursive) {
+            throw new Error(`EISDIR: is a directory, cp '${src}'`);
+        }
+        this.placeNode(normalizePath(dest), this.deepClone(srcNode));
+    }
+    async mv(src, dest) {
+        await this.cp(src, dest, { recursive: true });
+        await this.rm(src, { recursive: true });
+    }
+    async symlink(target, linkPath) {
+        validatePath(linkPath, 'symlink');
+        const segs = split(normalizePath(linkPath));
+        if (segs.length === 0) {
+            throw new Error(`EEXIST: file already exists, symlink '${linkPath}'`);
+        }
+        const parent = this.scaffold(segs);
+        const name = segs[segs.length - 1];
+        if (parent.children.has(name)) {
+            throw new Error(`EEXIST: file already exists, symlink '${linkPath}'`);
+        }
+        parent.children.set(name, {
+            kind: 'symlink',
+            target,
+            mode: SYMLINK_MODE,
+            mtime: new Date(),
+        });
+    }
+    async readlink(path) {
+        validatePath(path, 'readlink');
+        const loc = this.locate(path, false, 'readlink');
+        if (!loc)
+            throw this.missing('readlink', path);
+        if (loc.entry.kind !== 'symlink') {
+            throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
+        }
+        return loc.entry.target;
+    }
+    async realpath(path) {
+        validatePath(path, 'realpath');
+        const canon = this.canonicalize(path);
+        if (canon === null)
+            throw this.missing('realpath', path);
+        return canon;
+    }
+    resolvePath(base, path) {
+        return resolvePath(base, path);
+    }
+    async glob(pattern) {
+        const re = createGlobMatcher(pattern);
+        const hits = [];
+        this.gather(this.tree, '', re, hits);
+        return sortPaths(hits);
+    }
+    resolveNode(rawPath, followLast, op) {
+        if (normalizePath(rawPath) === '/')
+            return this.tree;
+        const loc = this.locate(rawPath, followLast, op);
+        return loc ? loc.entry : null;
+    }
+    locate(rawPath, followLast, op) {
+        const norm = normalizePath(rawPath);
+        if (norm === '/')
+            return null;
+        const pending = split(norm);
+        const trail = [];
+        let dir = this.tree;
+        let budget = MAX_SYMLINK_DEPTH;
+        while (pending.length > 0) {
+            const seg = pending.shift();
+            const child = dir.children.get(seg);
+            if (!child)
+                return null;
+            const last = pending.length === 0;
+            if (child.kind === 'symlink' && (!last || followLast)) {
+                if (--budget < 0) {
+                    throw new Error(`ELOOP: too many levels of symbolic links, ${op} '${rawPath}'`);
+                }
+                const base = trail.length > 0 ? '/' + trail.join('/') : '';
+                const abs = child.target.startsWith('/')
+                    ? normalizePath(child.target)
+                    : normalizePath(base + '/' + child.target);
+                pending.unshift(...split(abs));
+                trail.length = 0;
+                dir = this.tree;
+                continue;
+            }
+            if (last)
+                return { entry: child, parent: dir, key: seg };
+            if (child.kind !== 'dir')
+                return null;
+            trail.push(seg);
+            dir = child;
+        }
+        return null;
+    }
+    canonicalize(rawPath) {
+        const norm = normalizePath(rawPath);
+        if (norm === '/')
+            return '/';
+        const pending = split(norm);
+        const resolved = [];
+        let dir = this.tree;
+        let budget = MAX_SYMLINK_DEPTH;
+        while (pending.length > 0) {
+            const seg = pending.shift();
+            const child = dir.children.get(seg);
+            if (!child)
+                return null;
+            if (child.kind === 'symlink') {
+                if (--budget < 0) {
+                    throw new Error(`ELOOP: too many levels of symbolic links, realpath '${rawPath}'`);
+                }
+                const base = resolved.length > 0 ? '/' + resolved.join('/') : '';
+                const abs = child.target.startsWith('/')
+                    ? normalizePath(child.target)
+                    : normalizePath(base + '/' + child.target);
+                pending.unshift(...split(abs));
+                resolved.length = 0;
+                dir = this.tree;
+                continue;
+            }
+            resolved.push(seg);
+            if (child.kind === 'dir' && pending.length > 0) {
+                dir = child;
+            }
+            else if (pending.length > 0) {
+                return null;
+            }
+        }
+        return '/' + resolved.join('/');
+    }
+    insertContent(rawPath, content, encoding, mode, mtime) {
+        validatePath(rawPath, 'write');
+        const segs = split(normalizePath(rawPath));
+        if (segs.length === 0) {
+            throw new Error(`EISDIR: illegal operation on a directory, write '${rawPath}'`);
+        }
+        const parent = this.scaffold(segs);
+        parent.children.set(segs[segs.length - 1], {
+            kind: 'file',
+            bytes: toBuffer(content, encoding),
+            mode: mode ?? DEFAULT_FILE_MODE,
+            mtime: mtime ?? new Date(),
+        });
+    }
+    insertLazy(rawPath, provider, mode, mtime) {
+        validatePath(rawPath, 'write');
+        const segs = split(normalizePath(rawPath));
+        if (segs.length === 0)
+            return;
+        const parent = this.scaffold(segs);
+        parent.children.set(segs[segs.length - 1], {
+            kind: 'lazy',
+            provider,
+            mode: mode ?? DEFAULT_FILE_MODE,
+            mtime: mtime ?? new Date(),
+        });
+    }
+    async forceLazy(loc) {
+        const lazy = loc.entry;
+        const raw = await lazy.provider();
+        const bytes = typeof raw === 'string' ? utf8.encode(raw) : raw;
+        loc.parent.children.set(loc.key, {
+            kind: 'file',
+            bytes,
+            mode: lazy.mode,
+            mtime: lazy.mtime,
+        });
+        return bytes;
+    }
+    scaffold(segs) {
+        let dir = this.tree;
+        for (let i = 0; i < segs.length - 1; i++) {
+            const child = dir.children.get(segs[i]);
+            if (child && child.kind === 'dir') {
+                dir = child;
+            }
+            else {
+                const d = freshDir();
+                dir.children.set(segs[i], d);
+                dir = d;
+            }
+        }
+        return dir;
+    }
+    placeNode(normalized, entry) {
+        const segs = split(normalized);
+        if (segs.length === 0) {
+            throw new Error(`EISDIR: illegal operation on a directory, write '${normalized}'`);
+        }
+        const parent = this.scaffold(segs);
+        parent.children.set(segs[segs.length - 1], entry);
+    }
+    deepClone(entry) {
+        switch (entry.kind) {
+            case 'file':
+                return {
+                    kind: 'file',
+                    bytes: new Uint8Array(entry.bytes),
+                    mode: entry.mode,
+                    mtime: entry.mtime,
+                };
+            case 'lazy':
+                return { ...entry };
+            case 'symlink':
+                return { ...entry };
+            case 'dir': {
+                const clone = {
+                    kind: 'dir',
+                    children: new Map(),
+                    mode: entry.mode,
+                    mtime: entry.mtime,
+                };
+                for (const [k, v] of entry.children) {
+                    clone.children.set(k, this.deepClone(v));
+                }
+                return clone;
+            }
+        }
+    }
+    gather(dir, prefix, re, out) {
+        for (const [name, child] of dir.children) {
+            const full = prefix + '/' + name;
+            if (re.test(full))
+                out.push(full);
+            if (child.kind === 'dir')
+                this.gather(child, full, re, out);
+        }
+    }
+    missing(op, path) {
+        return new Error(`ENOENT: no such file or directory, ${op} '${path}'`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { FileSystem, FsStat, FileSystemDirent, FileSystemEntryType, BufferEncoding, FileContent, MkdirOptions, RmOptions, CpOptions, ReadFileOptions, WriteFileOptions, FileEntry, DirectoryEntry, SymlinkEntry, LazyFileEntry, FsEntry, FileInit, LazyFileProvider, InitialFiles, } from '@kuralle-agents/core';
+export { InMemoryFs, type FsData } from './in-memory-fs.js';
+export { CompositeFileSystem, type CompositeFileSystemConfig } from './composite-fs.js';
+export { normalizePath, validatePath, dirname, resolvePath, joinPath, resolveSymlinkTarget, createGlobMatcher, sortPaths, MAX_SYMLINK_DEPTH, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, SYMLINK_MODE, } from './path-utils.js';
+export { toBuffer, fromBuffer, getEncoding } from './encoding.js';
+export { createFsTool } from './tool.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { InMemoryFs } from './in-memory-fs.js';
+export { CompositeFileSystem } from './composite-fs.js';
+export { normalizePath, validatePath, dirname, resolvePath, joinPath, resolveSymlinkTarget, createGlobMatcher, sortPaths, MAX_SYMLINK_DEPTH, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, SYMLINK_MODE, } from './path-utils.js';
+export { toBuffer, fromBuffer, getEncoding } from './encoding.js';
+export { createFsTool } from './tool.js';

package/dist/interface.d.ts

@@ -0,0 +1 @@
+export type { FileSystem, FsStat, FileSystemDirent, FileSystemEntryType, BufferEncoding, FileContent, MkdirOptions, RmOptions, CpOptions, ReadFileOptions, WriteFileOptions, FileEntry, DirectoryEntry, SymlinkEntry, LazyFileEntry, FsEntry, FileInit, LazyFileProvider, InitialFiles, FsError, } from '@kuralle-agents/core';

package/dist/interface.js

@@ -0,0 +1 @@
+export {};

package/dist/path-utils.d.ts

@@ -0,0 +1,12 @@
+export declare const MAX_SYMLINK_DEPTH = 40;
+export declare const DEFAULT_DIR_MODE = 493;
+export declare const DEFAULT_FILE_MODE = 420;
+export declare const SYMLINK_MODE = 511;
+export declare function normalizePath(path: string): string;
+export declare function validatePath(path: string, operation: string): void;
+export declare function dirname(path: string): string;
+export declare function resolvePath(base: string, path: string): string;
+export declare function joinPath(parent: string, child: string): string;
+export declare function resolveSymlinkTarget(symlinkPath: string, target: string): string;
+export declare function createGlobMatcher(pattern: string): RegExp;
+export declare function sortPaths(paths: string[]): string[];