@archildata/client 0.1.7 → 0.1.9

package/README.md

@@ -68,31 +68,31 @@ The main client class for interacting with Archil filesystems.
 
 #### Metadata Operations
 
-- `getAttributes(inodeId, user?)` - Get inode attributes
-- `lookupInode(parentInodeId, name, user?)` - Lookup entry by name
-- `readDirectory(inodeId, offset?, cookie?, user?)` - List directory entries
-- `getExtendedAttribute(inodeId, name, user?)` - Get xattr value
-- `listExtendedAttributes(inodeId, user?)` - List xattr names
+- `getAttributes(inodeId, options?)` - Get inode attributes
+- `lookupInode(parentInodeId, name, options?)` - Lookup entry by name
+- `readDirectory(inodeId, options?)` - List directory entries
+- `getExtendedAttribute(inodeId, name, options?)` - Get xattr value
+- `listExtendedAttributes(inodeId, options?)` - List xattr names
 
 #### Data Operations
 
-- `readInode(inodeId, offset, length, user?)` - Read file data
-- `writeData(inodeId, offset, data, user?)` - Write file data (requires delegation)
+- `readInode(inodeId, offset, length, options?)` - Read file data
+- `writeData(inodeId, offset, data, options?)` - Write file data (requires delegation)
 - `sync()` - Sync all pending writes to server
 
 #### Delegation Operations
 
-- `checkout(inodeId, force?, user?)` - Acquire write delegation
-- `checkin(inodeId, user?)` - Release delegation
+- `checkout(inodeId, options?)` - Acquire write delegation
+- `checkin(inodeId, options?)` - Release delegation
 - `checkinAll()` - Release all delegations
 - `listDelegations()` - List currently held delegations
 
 #### Mutation Operations
 
-- `create(parentInodeId, name, attributes, user?)` - Create file/directory
-- `unlink(parentInodeId, name, user?)` - Delete file or empty directory
-- `rename(parentInodeId, name, newParentInodeId, newName, user?)` - Move/rename
-- `setattr(inodeId, options, user)` - Update file attributes
+- `create(parentInodeId, name, attributes, options?)` - Create file/directory
+- `unlink(parentInodeId, name, options?)` - Delete file or empty directory
+- `rename(parentInodeId, name, newParentInodeId, newName, options?)` - Move/rename
+- `setattr(inodeId, options)` - Update file attributes (user required in options)
 - `setImmutable(inodeId)` - Mark subtree as immutable
 - `setMutable(inodeId)` - Mark subtree as mutable
 - `listImmutableSubtrees()` - List immutable roots
@@ -134,6 +134,15 @@ interface DirectoryEntry {
   inodeType: string;
 }
 
+interface OperationOptions {
+  user?: UnixUser;    // Unix user context for permission checks
+}
+
+interface CheckoutOptions {
+  force?: boolean;    // Force revoke existing delegations (default: false)
+  user?: UnixUser;    // Unix user context for permission checks
+}
+
 interface SetAttrOptions {
   mode?: number;
   uid?: number;
@@ -141,6 +150,7 @@ interface SetAttrOptions {
   size?: number;
   atimeMs?: number;   // use -1 for current time
   mtimeMs?: number;   // use -1 for current time
+  user: UnixUser;     // required for setattr
 }
 ```
 

package/index.d.ts

@@ -148,6 +148,18 @@ export interface DelegationInfo {
   /** State of the delegation: "Active", "Pending", or "Removing" */
   state: string
 }
+/** Common options for operations that support user context */
+export interface OperationOptions {
+  /** Unix user context for permission checks */
+  user?: UnixUser
+}
+/** Options for checkout operation */
+export interface CheckoutOptions {
+  /** Force revoke existing delegations held by other clients (default: false) */
+  force?: boolean
+  /** Unix user context for permission checks */
+  user?: UnixUser
+}
 /**
  * Options for setattr operation
  *
@@ -169,6 +181,8 @@ export interface SetAttrOptions {
   mtimeMs?: number
   /** New change time in milliseconds since epoch */
   ctimeMs?: number
+  /** Unix user context for permission checks (required for setattr) */
+  user?: UnixUser
 }
 /**
  * ArchilClient provides low-level access to Archil filesystem operations.
@@ -205,9 +219,9 @@ export declare class ArchilClient {
    */
   close(): Promise<number>
   /** Get attributes for an inode (uses cache). */
-  getAttributes(inodeId: number, user?: UnixUser | undefined | null): Promise<InodeAttributes>
+  getAttributes(inodeId: number, options?: OperationOptions | undefined | null): Promise<InodeAttributes>
   /** Lookup an entry by name in a directory (uses cache). */
-  lookupInode(parentInodeId: number, name: string, user?: UnixUser | undefined | null): Promise<LookupResponse>
+  lookupInode(parentInodeId: number, name: string, options?: OperationOptions | undefined | null): Promise<LookupResponse>
   /**
    * Read directory entries.
    *
@@ -215,30 +229,42 @@ export declare class ArchilClient {
    * the dirent cache is properly populated. This ensures that subsequent
    * lookup_inode calls can find the entries returned here.
    */
-  readDirectory(inodeId: number, offset?: number | undefined | null, cookie?: number | undefined | null, user?: UnixUser | undefined | null): Promise<Array<DirectoryEntry>>
+  readDirectory(inodeId: number, options?: OperationOptions | undefined | null): Promise<Array<DirectoryEntry>>
   /** Get an extended attribute value. */
-  getExtendedAttribute(inodeId: number, name: string, user?: UnixUser | undefined | null): Promise<Buffer | null>
+  getExtendedAttribute(inodeId: number, name: string, options?: OperationOptions | undefined | null): Promise<Buffer | null>
   /** List all extended attribute names. */
-  listExtendedAttributes(inodeId: number, user?: UnixUser | undefined | null): Promise<Array<string>>
+  listExtendedAttributes(inodeId: number, options?: OperationOptions | undefined | null): Promise<Array<string>>
   /**
    * Read data from a file (uses cache).
    *
    * Returns zero-copy Buffer when possible for optimal performance.
    */
-  readInode(inodeId: number, offset: number, length: number, user?: UnixUser | undefined | null): Promise<Buffer>
+  readInode(inodeId: number, offset: number, length: number, options?: OperationOptions | undefined | null): Promise<Buffer>
   /**
    * Checkout (acquire delegation for) an inode for writing.
    *
    * This tracks the delegation locally so that subsequent write operations
    * can proceed without additional server round-trips for permission checks.
+   *
+   * @example
+   * ```typescript
+   * // Basic checkout
+   * await client.checkout(inodeId);
+   *
+   * // Force revoke existing delegations from other clients
+   * await client.checkout(inodeId, { force: true });
+   *
+   * // With user context
+   * await client.checkout(inodeId, { force: true, user: { uid: 1000, gid: 1000 } });
+   * ```
    */
-  checkout(inodeId: number, force?: boolean | undefined | null, user?: UnixUser | undefined | null): Promise<void>
+  checkout(inodeId: number, options?: CheckoutOptions | undefined | null): Promise<void>
   /**
    * Checkin (release delegation for) an inode.
    *
    * This syncs any pending writes and releases the local delegation tracking.
    */
-  checkin(inodeId: number, user?: UnixUser | undefined | null): Promise<void>
+  checkin(inodeId: number, options?: OperationOptions | undefined | null): Promise<void>
   /** Release all delegations held by this client. */
   checkinAll(): Promise<number>
   /**
@@ -258,14 +284,14 @@ export declare class ArchilClient {
    * @example
    * ```typescript
    * // First checkout to get write delegation
-   * await client.checkout(inodeId, false, user);
+   * await client.checkout(inodeId);
    * // Then write data
-   * await client.writeData(inodeId, 0n, Buffer.from('Hello World'), user);
+   * await client.writeData(inodeId, 0, Buffer.from('Hello World'));
    * // Optionally checkin when done
-   * await client.checkin(inodeId, user);
+   * await client.checkin(inodeId);
    * ```
    */
-  writeData(inodeId: number, offset: number, data: Buffer, user?: UnixUser | undefined | null): Promise<void>
+  writeData(inodeId: number, offset: number, data: Buffer, options?: OperationOptions | undefined | null): Promise<void>
   /**
    * Set attributes on an inode.
    *
@@ -277,23 +303,23 @@ export declare class ArchilClient {
    * @example
    * ```typescript
    * // First checkout to get write delegation
-   * await client.checkout(inodeId, false, user);
+   * await client.checkout(inodeId);
    * // Update timestamps (touch)
-   * await client.setattr(inodeId, { atimeMs: -1, mtimeMs: -1 }, user);
+   * await client.setattr(inodeId, { atimeMs: -1, mtimeMs: -1, user: { uid: 1000, gid: 1000 } });
    * // Or change mode
-   * await client.setattr(inodeId, { mode: 0o755 }, user);
+   * await client.setattr(inodeId, { mode: 0o755, user: { uid: 1000, gid: 1000 } });
    * // Checkin when done
-   * await client.checkin(inodeId, user);
+   * await client.checkin(inodeId);
    * ```
    */
-  setattr(inodeId: number, options: SetAttrOptions, user: UnixUser): Promise<InodeAttributes>
+  setattr(inodeId: number, options: SetAttrOptions): Promise<InodeAttributes>
   /**
    * Unlink (delete) a file or empty directory.
    *
    * Removes the directory entry from the parent directory. Requires
    * write permission on the parent directory.
    */
-  unlink(parentInodeId: number, name: string, user?: UnixUser | undefined | null): Promise<void>
+  unlink(parentInodeId: number, name: string, options?: OperationOptions | undefined | null): Promise<void>
   /**
    * Rename (move) a file or directory.
    *
@@ -303,10 +329,10 @@ export declare class ArchilClient {
    * @example
    * ```typescript
    * // Move a file
-   * await client.rename(srcParentInodeId, 'oldname.txt', destParentInodeId, 'newname.txt', user);
+   * await client.rename(srcParentInodeId, 'oldname.txt', destParentInodeId, 'newname.txt');
    * ```
    */
-  rename(parentInodeId: number, name: string, newParentInodeId: number, newName: string, user?: UnixUser | undefined | null): Promise<void>
+  rename(parentInodeId: number, name: string, newParentInodeId: number, newName: string, options?: OperationOptions | undefined | null): Promise<void>
   /**
    * Create a new file or directory.
    *
@@ -315,7 +341,7 @@ export declare class ArchilClient {
    *
    * Returns the inode ID of the created file.
    */
-  create(parentInodeId: number, name: string, attributes: InodeAttributes, user?: UnixUser | undefined | null): Promise<number>
+  create(parentInodeId: number, name: string, attributes: InodeAttributes, options?: OperationOptions | undefined | null): Promise<number>
   /** Mark an inode subtree as immutable. */
   setImmutable(inodeId: number): Promise<void>
   /** Mark an inode subtree as mutable (reverse of set_immutable). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archildata/client",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "High-performance Node.js client for Archil distributed filesystem",
   "main": "index.js",
   "types": "index.d.ts",
@@ -50,10 +50,10 @@
     "native"
   ],
   "optionalDependencies": {
-    "@archildata/client-win32-x64-msvc": "0.1.7",
-    "@archildata/client-darwin-x64": "0.1.7",
-    "@archildata/client-linux-x64-gnu": "0.1.7",
-    "@archildata/client-darwin-arm64": "0.1.7",
-    "@archildata/client-linux-arm64-gnu": "0.1.7"
+    "@archildata/client-win32-x64-msvc": "0.1.9",
+    "@archildata/client-darwin-x64": "0.1.9",
+    "@archildata/client-linux-x64-gnu": "0.1.9",
+    "@archildata/client-darwin-arm64": "0.1.9",
+    "@archildata/client-linux-arm64-gnu": "0.1.9"
   }
 }