@axium/storage 0.7.10 → 0.9.0

package/dist/{client.d.ts → client/api.d.ts}

@@ -1,4 +1,4 @@
-import type { StorageItemMetadata, StorageItemUpdate, UserStorage, UserStorageInfo } from './common.js';
+import type { StorageItemMetadata, StorageItemUpdate, UserStorage, UserStorageInfo } from '../common.js';
 export declare function parseItem(result: StorageItemMetadata): StorageItemMetadata;
 export interface UploadOptions {
     parentId?: string;
@@ -15,7 +15,7 @@ export declare function downloadItem(fileId: string): Promise<Blob>;
 export declare function updateItemMetadata(fileId: string, metadata: StorageItemUpdate): Promise<StorageItemMetadata>;
 export declare function deleteItem(fileId: string): Promise<StorageItemMetadata>;
 export declare function getUserStorage(userId: string): Promise<UserStorage>;
-export declare function getUserStorageInfo(userId: string): Promise<UserStorageInfo>;
+export declare function getUserStats(userId: string): Promise<UserStorageInfo>;
 export declare function getUserTrash(userId: string): Promise<StorageItemMetadata[]>;
 export declare function itemsSharedWith(userId: string): Promise<StorageItemMetadata[]>;
 export declare function getUserStorageRoot(userId: string): Promise<StorageItemMetadata[]>;

package/dist/{client.js → client/api.js}

@@ -1,4 +1,4 @@
-import { fetchAPI, token } from '@axium/client/requests';
+import { fetchAPI, prefix, token } from '@axium/client/requests';
 async function _upload(method, url, data, extraHeaders = {}) {
     const init = {
         method,
@@ -30,16 +30,24 @@ export function parseItem(result) {
         result.trashedAt = new Date(result.trashedAt);
     return result;
 }
+function rawStorage(fileId) {
+    const raw = '/raw/storage' + (fileId ? '/' + fileId : '');
+    if (prefix[0] == '/')
+        return raw;
+    const url = new URL(prefix);
+    url.pathname = raw;
+    return url;
+}
 export async function uploadItem(file, opt = {}) {
     const headers = {};
     if (opt.parentId)
         headers['x-parent'] = opt.parentId;
     if (opt.name)
         headers['x-name'] = opt.name;
-    return parseItem(await _upload('PUT', '/raw/storage', file, headers));
+    return parseItem(await _upload('PUT', rawStorage(), file, headers));
 }
 export async function updateItem(fileId, data) {
-    return parseItem(await _upload('POST', '/raw/storage/' + fileId, data));
+    return parseItem(await _upload('POST', rawStorage(fileId), data));
 }
 export async function getItemMetadata(fileId) {
     const result = await fetchAPI('GET', 'storage/item/:id', undefined, fileId);
@@ -55,7 +63,7 @@ export async function getDirectoryMetadata(parentId) {
     return result;
 }
 export async function downloadItem(fileId) {
-    const response = await fetch('/raw/storage/' + fileId, {
+    const response = await fetch(rawStorage(fileId), {
         headers: token ? { Authorization: 'Bearer ' + token } : {},
     });
     if (!response.ok)
@@ -72,12 +80,19 @@ export async function deleteItem(fileId) {
 }
 export async function getUserStorage(userId) {
     const result = await fetchAPI('GET', 'users/:id/storage', undefined, userId);
+    result.lastModified = new Date(result.lastModified);
+    if (result.lastTrashed)
+        result.lastTrashed = new Date(result.lastTrashed);
     for (const item of result.items)
         parseItem(item);
     return result;
 }
-export async function getUserStorageInfo(userId) {
-    return await fetchAPI('OPTIONS', 'users/:id/storage', undefined, userId);
+export async function getUserStats(userId) {
+    const result = await fetchAPI('OPTIONS', 'users/:id/storage', undefined, userId);
+    result.lastModified = new Date(result.lastModified);
+    if (result.lastTrashed)
+        result.lastTrashed = new Date(result.lastTrashed);
+    return result;
 }
 export async function getUserTrash(userId) {
     const result = await fetchAPI('GET', 'users/:id/storage/trash', undefined, userId);

package/dist/client/cli.d.ts

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

package/dist/client/cli.js

@@ -0,0 +1,194 @@
+import { configDir, session } from '@axium/client/cli/config';
+import { formatBytes } from '@axium/core/format';
+import * as io from '@axium/core/node/io';
+import { Option, program } from 'commander';
+import { statSync, unlinkSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { styleText } from 'node:util';
+import { colorItem, formatItems } from '../node.js';
+import * as api from './api.js';
+import { config, saveConfig } from './config.js';
+import { cachePath, getDirectory, resolveItem, setQuiet, syncCache } from './local.js';
+import { computeDelta, doSync, fetchSyncItems } from './sync.js';
+const cli = program
+    .command('files')
+    .helpGroup('Plugins:')
+    .description('CLI integration for @axium/storage')
+    .option('-q, --quiet', 'Suppress output')
+    .hook('preAction', (action) => {
+    const opts = action.optsWithGlobals();
+    if (opts.quiet)
+        setQuiet(true);
+});
+cli.command('usage')
+    .description('Show your usage')
+    .action(async () => {
+    const { limits, itemCount, usedBytes } = await api.getUserStats(session().userId);
+    console.log(`Items: ${itemCount} ${limits.user_items ? ' / ' + limits.user_items : ''}`);
+    console.log(`Space: ${formatBytes(usedBytes)} ${limits.user_size ? ' / ' + formatBytes(limits.user_size * 1_000_000) : ''}`);
+});
+cli.command('ls')
+    .alias('list')
+    .description('List the contents of a folder')
+    .argument('<path>', 'remote folder path')
+    .option('-l, --long', 'Show more details')
+    .option('-h, --human-readable', 'Show sizes in human readable format')
+    .action(async function (path) {
+    const { users } = await syncCache().catch(io.handleError);
+    const { long, humanReadable } = this.optsWithGlobals();
+    const items = await getDirectory(path).catch(io.handleError);
+    if (!long) {
+        console.log(items.map(colorItem).join('\t'));
+        return;
+    }
+    console.log('total ' + items.length);
+    for (const text of formatItems({ items, users, humanReadable }))
+        console.log(text);
+});
+cli.command('mkdir')
+    .description('Create a remote folder')
+    .argument('<path>', 'remote folder path to create')
+    .action(async (path) => {
+    const pathParts = path.split('/');
+    const name = pathParts.pop();
+    const parentPath = pathParts.join('/');
+    const parent = !parentPath ? null : await resolveItem(parentPath).catch(io.handleError);
+    if (parent) {
+        if (!parent)
+            io.exit('Could not resolve parent folder.');
+        if (parent.type != 'inode/directory')
+            io.exit('Parent path is not a directory.');
+    }
+    await api.uploadItem(new Blob([], { type: 'inode/directory' }), { parentId: parent?.id, name }).catch(io.handleError);
+});
+cli.command('status')
+    .option('-v, --verbose', 'Show more details')
+    .option('--refresh', 'Force refresh metadata from the server')
+    .action(async (opt) => {
+    console.log(styleText('bold', `${config.sync.length} synced folder(s):`));
+    for (const sync of config.sync) {
+        if (opt.refresh)
+            await fetchSyncItems(sync.item, sync.name);
+        const delta = computeDelta(sync);
+        if (opt.verbose) {
+            console.log(styleText('underline', sync.local_path + ':'));
+            if (delta.synced.length == delta.items.length && !delta.local_only.length) {
+                console.log('\t' + styleText('blueBright', 'All files are synced!'));
+                continue;
+            }
+            for (const { _path } of delta.local_only)
+                console.log('\t' + styleText('green', '+ ' + _path));
+            for (const { path } of delta.remote_only)
+                console.log('\t' + styleText('red', '- ' + path));
+            for (const { path, modifiedAt } of delta.modified) {
+                const outdated = modifiedAt.getTime() > statSync(join(sync.local_path, path)).mtime.getTime();
+                console.log('\t' + styleText('yellow', '~ ' + path) + (outdated ? ' (outdated)' : ''));
+            }
+        }
+        else {
+            console.log(sync.local_path + ':', Object.entries(delta)
+                .map(([name, items]) => `${styleText('blueBright', items.length.toString())} ${name.replaceAll('_', '-')}`)
+                .join(', '));
+        }
+    }
+});
+cli.command('add')
+    .description('Add a folder to be synced')
+    .argument('<path>', 'local path to the folder to sync')
+    .argument('<remote>', 'remote folder path')
+    .action(async (localPath, remoteName) => {
+    localPath = resolve(localPath);
+    for (const sync of config.sync) {
+        if (sync.local_path == localPath || localPath.startsWith(sync.local_path + '/'))
+            io.exit('This local path is already being synced.');
+        if (sync.remote_path == remoteName || remoteName.startsWith(sync.remote_path + '/'))
+            io.exit('This remote path is already being synced.');
+    }
+    const local = await stat(localPath).catch(e => io.exit(e.toString()));
+    if (!local.isDirectory())
+        io.exit('Local path is not a directory.');
+    const remote = await resolveItem(remoteName);
+    if (!remote)
+        io.exit('Could not resolve remote path.');
+    if (remote.type != 'inode/directory')
+        io.exit('Remote path is not a directory.');
+    config.sync.push({
+        name: remote.name,
+        item: remote.id,
+        local_path: localPath,
+        last_synced: new Date(),
+        remote_path: remoteName,
+        include_dotfiles: false,
+        exclude: [],
+    });
+    await fetchSyncItems(remote.id);
+    saveConfig();
+});
+cli.command('unsync')
+    .alias('remove-sync')
+    .alias('rm-sync')
+    .description('Stop syncing a folder')
+    .argument('<path>', 'local path to the folder to stop syncing')
+    .action((localPath) => {
+    localPath = resolve(localPath);
+    const index = config.sync.findIndex(sync => sync.local_path == localPath);
+    if (index == -1)
+        io.exit('This local path is not being synced.');
+    unlinkSync(join(configDir, 'sync', config.sync[index].item + '.json'));
+    config.sync.splice(index, 1);
+    saveConfig();
+});
+cli.command('sync')
+    .description('Sync files')
+    .addOption(new Option('--delete <mode>', 'Delete local/remote files that were deleted remotely/locally')
+    .choices(['local', 'remote', 'none'])
+    .default('none'))
+    .option('-d, --dry-run', 'Show what would be done, but do not make any changes')
+    .option('-v, --verbose', 'Show more details')
+    .argument('[sync]', 'The name of the Sync to sync')
+    .action(async (name, opt) => {
+    if (name) {
+        const sync = config.sync.find(s => s.name == name);
+        if (!sync)
+            io.exit('Can not find a Sync with that name.');
+        await doSync(sync, opt);
+    }
+    else
+        for (const sync of config.sync)
+            await doSync(sync, opt);
+});
+const cliCache = cli.command('cache').description('Manage the local cache');
+cliCache
+    .command('clear')
+    .description('Clear the local cache')
+    .action(() => unlinkSync(cachePath));
+cliCache
+    .command('refresh')
+    .description('Force a refresh of the local cache from the server')
+    .action(async () => {
+    await syncCache(true).catch(io.handleError);
+});
+cliCache
+    .command('dump')
+    .description('Dump the local cache')
+    .option('-v, --verbose', 'Show more details')
+    .addOption(new Option('-j, --json', 'Output as JSON').conflicts(['verbose', 'quiet']))
+    .action(async function () {
+    const opt = this.optsWithGlobals();
+    const data = await syncCache(false).catch(io.handleError);
+    if (opt.json) {
+        console.log(JSON.stringify(data));
+        return;
+    }
+    console.log(`Cache contains ${data.items.length} items and ${Object.keys(data.users).length} users.`);
+    if (opt.quiet || !opt.verbose)
+        return;
+    console.log(styleText('bold', 'Items:'));
+    for (const text of formatItems({ ...data, humanReadable: true }))
+        console.log(text);
+    console.log(styleText('bold', 'Users:'));
+    for (const user of Object.values(data.users)) {
+        console.log(user.name, `<${user.email}>`, styleText('dim', `(${user.id})`));
+    }
+});

package/dist/client/config.d.ts

@@ -0,0 +1,17 @@
+import * as z from 'zod';
+declare const ClientStorageConfig: z.ZodObject<{
+    sync: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        item: z.ZodUUID;
+        local_path: z.ZodString;
+        last_synced: z.ZodCoercedDate<unknown>;
+        remote_path: z.ZodString;
+        include_dotfiles: z.ZodDefault<z.ZodBoolean>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export interface ClientStorageConfig extends z.infer<typeof ClientStorageConfig> {
+}
+export declare let config: ClientStorageConfig;
+export declare function saveConfig(): void;
+export {};

package/dist/client/config.js

@@ -0,0 +1,20 @@
+import { configDir } from '@axium/client/cli/config';
+import { debug, readJSON, writeJSON } from '@axium/core/node/io';
+import { join } from 'node:path/posix';
+import * as z from 'zod';
+import { Sync } from './sync.js';
+const ClientStorageConfig = z.looseObject({
+    sync: Sync.array(),
+});
+const configPath = join(configDir, 'storage.json');
+export let config = { sync: [] };
+try {
+    config = readJSON(configPath, ClientStorageConfig);
+}
+catch (e) {
+    debug('Could not load @axium/storage config: ' + e);
+}
+export function saveConfig() {
+    writeJSON(configPath, config);
+    debug('Saved @axium/storage config.');
+}

package/dist/client/hooks.d.ts

@@ -0,0 +1 @@
+export declare function run(): Promise<void>;

package/dist/client/hooks.js

@@ -0,0 +1,6 @@
+import { config } from './config.js';
+import { doSync } from './sync.js';
+export async function run() {
+    for (const sync of config.sync)
+        await doSync(sync, { delete: 'none', dryRun: false, verbose: true });
+}

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export * from './api.js';

package/dist/client/index.js

@@ -0,0 +1 @@
+export * from './api.js';

package/dist/client/local.d.ts

@@ -0,0 +1,58 @@
+import { UserPublic } from '@axium/core';
+import * as z from 'zod';
+import { StorageItemMetadata } from '../common.js';
+export declare function setQuiet(enabled: boolean): void;
+export declare function walkItems(path: string, items: StorageItemMetadata[]): StorageItemMetadata | null;
+declare const StorageCache: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        createdAt: z.ZodCoercedDate<unknown>;
+        dataURL: z.ZodString;
+        hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        id: z.ZodUUID;
+        immutable: z.ZodBoolean;
+        modifiedAt: z.ZodCoercedDate<unknown>;
+        name: z.ZodString;
+        userId: z.ZodUUID;
+        parentId: z.ZodNullable<z.ZodUUID>;
+        publicPermission: z.ZodEnum<{
+            readonly None: 0;
+            readonly Read: 1;
+            readonly Comment: 2;
+            readonly Edit: 3;
+            readonly Manage: 5;
+        }> & {
+            readonly None: 0;
+            readonly Read: 1;
+            readonly Comment: 2;
+            readonly Edit: 3;
+            readonly Manage: 5;
+        };
+        size: z.ZodInt;
+        trashedAt: z.ZodNullable<z.ZodCoercedDate<unknown>>;
+        type: z.ZodString;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    users: z.ZodRecord<z.ZodUUID, z.ZodObject<{
+        id: z.ZodUUID;
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodEmail>;
+        emailVerified: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
+        image: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+        preferences: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        roles: z.ZodArray<z.ZodString>;
+        registeredAt: z.ZodCoercedDate<unknown>;
+        isAdmin: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+interface StorageCache extends z.infer<typeof StorageCache> {
+    users: Record<string, UserPublic>;
+}
+export declare const cachePath: string;
+export declare let cachedData: StorageCache | null;
+/**
+ * @param force true => always refresh, false => never refresh, null (default) => refresh if outdated
+ */
+export declare function syncCache(force?: boolean | null): Promise<StorageCache>;
+export declare function resolveItem(path: string): Promise<StorageItemMetadata | null>;
+export declare function getDirectory(path: string): Promise<StorageItemMetadata[]>;
+export {};

package/dist/client/local.js

@@ -0,0 +1,90 @@
+import { cacheDir, session } from '@axium/client/cli/config';
+import { userInfo } from '@axium/client/user';
+import { UserPublic } from '@axium/core';
+import * as io from '@axium/core/node/io';
+import { ENOENT, ENOTDIR } from 'node:constants';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as z from 'zod';
+import { StorageItemMetadata } from '../common.js';
+import { getUserStats, getUserStorage } from './api.js';
+let quiet = false;
+export function setQuiet(enabled) {
+    quiet = enabled;
+}
+export function walkItems(path, items) {
+    const resolved = [];
+    let currentItem = null, currentParentId = null;
+    const target = path.split('/').filter(p => p);
+    for (const part of target) {
+        for (const item of items) {
+            if (item.parentId != currentParentId || item.name != part)
+                continue;
+            currentItem = item;
+            currentParentId = item.id;
+            resolved.push(part);
+            break;
+        }
+    }
+    return currentItem;
+}
+const StorageCache = z.object({
+    items: StorageItemMetadata.array(),
+    users: z.record(z.uuid(), UserPublic),
+});
+export const cachePath = join(cacheDir, 'storage.json');
+export let cachedData = null;
+/**
+ * @param force true => always refresh, false => never refresh, null (default) => refresh if outdated
+ */
+export async function syncCache(force = null) {
+    if (cachedData)
+        return cachedData;
+    const cacheUpdated = await stat(cachePath)
+        .then(stats => stats.mtimeMs)
+        .catch(() => 0);
+    const { userId } = session();
+    let { lastModified, lastTrashed } = await getUserStats(userId);
+    lastTrashed ??= new Date(0);
+    if ((force || cacheUpdated < lastModified.getTime() || cacheUpdated < lastTrashed.getTime()) && force !== false) {
+        if (!quiet)
+            io.start('Updating and loading item metadata');
+        try {
+            const { items } = await getUserStorage(userId);
+            const users = {};
+            for (const item of items) {
+                users[item.userId] ||= await userInfo(item.userId);
+            }
+            cachedData = { items, users };
+            io.writeJSON(cachePath, cachedData);
+            if (!quiet)
+                io.done();
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            if (quiet)
+                io.exit('Failed to update item metadata: ' + message);
+            else
+                io.exit(message);
+        }
+    }
+    else {
+        cachedData = io.readJSON(cachePath, StorageCache);
+    }
+    return cachedData;
+}
+export async function resolveItem(path) {
+    const { items } = await syncCache();
+    return walkItems(path, items);
+}
+export async function getDirectory(path) {
+    const { items } = await syncCache();
+    if (path == '/' || path == '')
+        return items.filter(item => item.parentId === null);
+    const dir = walkItems(path, items);
+    if (!dir)
+        throw ENOENT;
+    if (dir.type != 'inode/directory')
+        throw ENOTDIR;
+    return items.filter(item => item.parentId === dir.id);
+}

package/dist/client/sync.d.ts

@@ -0,0 +1,67 @@
+import * as fs from 'node:fs';
+import * as z from 'zod';
+import '../polyfills.js';
+/**
+ * A Sync is a storage item that has been selected for synchronization by the user.
+ * Importantly, it is *only* the "top-level" item.
+ * This means if a user selects a directory to sync, only that directory is a Sync.
+ *
+ * `Sync`s are client-side in nature, the server does not care about them.
+ * (we could do something fancy server-side at a later date)
+ */
+export declare const Sync: z.ZodObject<{
+    name: z.ZodString;
+    item: z.ZodUUID;
+    local_path: z.ZodString;
+    last_synced: z.ZodCoercedDate<unknown>;
+    remote_path: z.ZodString;
+    include_dotfiles: z.ZodDefault<z.ZodBoolean>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export interface Sync extends z.infer<typeof Sync> {
+}
+/** Local metadata about a storage item to sync */
+export declare const LocalItem: z.ZodObject<{
+    id: z.ZodUUID;
+    path: z.ZodString;
+    modifiedAt: z.ZodCoercedDate<unknown>;
+    hash: z.ZodOptional<z.ZodNullable<z.ZodCustomStringFormat<"hex">>>;
+}, z.core.$strip>;
+export interface LocalItem extends z.infer<typeof LocalItem> {
+}
+export declare function fetchSyncItems(id: string, folderName?: string): Promise<LocalItem[]>;
+export declare function getItems(id: string): LocalItem[];
+export declare function setItems(id: string, items: LocalItem[]): void;
+/** Metadata about a synced storage item. */
+export interface ItemMetadata {
+}
+/** Computed metadata about changes */
+export interface Delta {
+    synced: LocalItem[];
+    modified: LocalItem[];
+    remote_only: LocalItem[];
+    items: LocalItem[];
+    _items: Map<string, LocalItem>;
+    local_only: (fs.Dirent<string> & {
+        _path: string;
+    })[];
+}
+/**
+ * Computes the changes between the local and remote, in the direction of the remote.
+ */
+export declare function computeDelta(sync: Sync): Delta;
+/**
+ * A helper to run an action on an array, with support for dry-runs and displaying a progress counter or listing each item.
+ */
+export declare function applyAction<T>(opt: {
+    dryRun: boolean;
+    verbose: boolean;
+}, items: T[], label: (item: T) => string, action: (item: T) => Promise<void | string> | void | string): Promise<void>;
+export interface SyncOptions {
+    delete: 'local' | 'remote' | 'none';
+    dryRun: boolean;
+    verbose: boolean;
+}
+export interface SyncStats {
+}
+export declare function doSync(sync: Sync, opt: SyncOptions): Promise<SyncStats>;