From 0c8dd8b6e4b0318727fb4bde0e39c1ba981cb7ba Mon Sep 17 00:00:00 2001 From: Juan Castro Date: Tue, 25 Aug 2026 17:45:15 -0400 Subject: [PATCH] Document the share flag and returnShares --- src/docs/src/FS/readdir.md | 2 ++ src/docs/src/FS/stat.md | 32 +++++++++++++++++++ src/docs/src/Objects/fsitem.md | 4 +++ .../playground/examples/fs-stat-shares.html | 17 ++++++++++ 4 files changed, 55 insertions(+) create mode 100644 src/docs/src/playground/examples/fs-stat-shares.html diff --git a/src/docs/src/FS/readdir.md b/src/docs/src/FS/readdir.md index a51a03a35..d26cc3c45 100755 --- a/src/docs/src/FS/readdir.md +++ b/src/docs/src/FS/readdir.md @@ -41,6 +41,8 @@ An object with the following properties: A `Promise` that resolves to an array of [`FSItem`](/Objects/fsitem/) objects (files and directories) within the specified directory. +Each item carries `is_shared`: `true` when you have shared it with someone, `false` when you have not, and `null` for items that are not yours. Only shares on the item itself count — the children of a folder you shared report `false`, since the share lives on the folder. Use [`getShares()`](/FS/getShares/) on an item to see who can reach it, including access inherited from a parent. + When the request includes `cursor` (even `null`) or `includeTotal`, the promise instead resolves to a page object: - `items` (Array): The [`FSItem`](/Objects/fsitem/) objects on this page. diff --git a/src/docs/src/FS/stat.md b/src/docs/src/FS/stat.md index 77ccc22b4..86415380d 100755 --- a/src/docs/src/FS/stat.md +++ b/src/docs/src/FS/stat.md @@ -31,11 +31,16 @@ An object with the following properties: - `returnPermissions` (Boolean) - Whether to return permission information. Defaults to `false`. - `returnVersions` (Boolean) - Whether to return version information. Defaults to `false`. - `returnSize` (Boolean) - Whether to return size information. Defaults to `false`. +- `returnShares` (Boolean) - Whether to include who the item is shared with, as a `shares` array on the result. Defaults to `false`. ## Return value A `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of the specified file or directory. +The item carries `is_shared`: `true` when you have shared it with someone, `false` when you have not, and `null` when the item is not yours — whether someone else's file has other recipients is not yours to see. Only shares **on the item itself** count. A file inside a folder you shared is reachable through that folder without being shared itself, so it reports `false`; [`getShares()`](/FS/getShares/) is what reports inherited access. + +With `returnShares: true`, the result also carries `shares` — an array of the same share objects [`getShares()`](/FS/getShares/) returns, including access inherited from a parent folder and unclaimed invitations. It is empty unless you own the item or hold `manage` on it, so asking for it never fails a `stat()` you were otherwise allowed to make. + ## Examples Get information about a file @@ -61,3 +66,30 @@ A `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of the speci ``` + +See whether a file is shared, and with whom + +```html;fs-stat-shares + + + + + + +``` + +## Related + +- [`puter.fs.getShares()`](/FS/getShares/) - List who can reach an item +- [`puter.fs.share()`](/FS/share/) - Grant access diff --git a/src/docs/src/Objects/fsitem.md b/src/docs/src/Objects/fsitem.md index 024aa5461..fa4aab523 100755 --- a/src/docs/src/Objects/fsitem.md +++ b/src/docs/src/Objects/fsitem.md @@ -40,6 +40,10 @@ An integer containing the Unix timestamp of the date and time when the item was An integer containing the size of the item in bytes. If the item is a directory, this will be `null`. +#### `is_shared` (Boolean | null) + +Whether you have shared this item with anyone: `true` if you have, `false` if you have not, and `null` when the item is not yours. Only shares on the item itself count, not access inherited from a shared parent folder. Set by [`stat()`](/FS/stat/) and [`readdir()`](/FS/readdir/); absent on items obtained any other way. + ## Methods ### `read()` diff --git a/src/docs/src/playground/examples/fs-stat-shares.html b/src/docs/src/playground/examples/fs-stat-shares.html new file mode 100644 index 000000000..dd44c26db --- /dev/null +++ b/src/docs/src/playground/examples/fs-stat-shares.html @@ -0,0 +1,17 @@ + + + + + +