fission-sdk - npm Package Compare versions

Comparing version 0.15.0-alpha1 to 0.15.0

package.json

 {
   "name": "fission-sdk",
-  "version": "0.15.0-alpha1",
+  "version": "0.15.0",
   "description": "Fission Typescript SDK",
@@ -102,3 +102,2 @@ "keywords": [],
     "base58-universal": "^1.0.0",
-    "bloomfilter": "^0.0.18",
     "borc": "^2.1.1",
@@ -105,0 +104,0 @@ "ipld-dag-pb": "^0.18.2",

README.md

@@ -24,8 +24,9 @@ ![](https://github.com/fission-suite/ts-sdk/raw/master/assets/logo.png?sanitize=true)
   (a lobby is where you can make a Fission account or link an account)
-- managing your web native **file system**
+- managing your web native **file system**  
+  (this is where a user's data lives)
 - tools for building DIDs and UCANs.
 
-```js
+```ts
 // ES6
-import sdk from 'fission-sdk'
+import * as sdk from 'fission-sdk'
 
@@ -40,25 +41,22 @@ // Browser/UMD build
 
-# Authentication
+# Getting Started
 
-[auth.fission.codes](https://auth.fission.codes) is our authentication lobby, where you'll be able to make a Fission an account and link with another account that's on another device or browser.
+```ts
+const { scenario, state } = await sdk.initialise()
 
-```js
-const auth = await sdk.isAuthenticated()
-
-if (auth.cancelled) {
+if (scenario.authCancelled) {
   // User was redirected to lobby,
   // but cancelled the authorisation.
 
-} else if (auth.newUser) {
-  // This authenticated user is new to Fission.
-
-} else if (auth.authenticated) {
-  // Authenticated 🍿
+} else if (scenario.authSucceeded || scenario.continuum) {
+  // State:
+  // state.authenticated    -  Will always be `true` in these scenarios
+  // state.newUser          -  If the user is new to Fission
+  // state.throughLobby     -  If the user authenticated through the lobby, or just came back.
+  // state.username         -  The user's username.
   //
-  // additional data:
-  // auth.throughLobby  -  If the user authenticated through the lobby, or just came back.
-  // auth.username      -  User's username
+  // ☞ We can now interact with our file system (more on that later)
+  state.fs
 
-} else {
-  // Not authenticated 🙅‍♀️
+} else if (scenario.notAuthenticated) {
   sdk.redirectToLobby()
@@ -69,3 +67,3 @@
 
-`redirectToLobby` takes an optional parameter, the url that the lobby should redirect back to (the default is `location.href`).
+`redirectToLobby` will redirect you to [auth.fission.codes](https://auth.fission.codes) our authentication lobby, where you'll be able to make a Fission an account and link with another account that's on another device or browser. The function takes an optional parameter, the url that the lobby should redirect back to (the default is `location.href`).
 
@@ -86,3 +84,17 @@
 
+```ts
+// After authenticating …
+const fs = state.fs
 
+// List the user's private files that belong to this app
+const appPath = fs.appPath.private("myApp")
+
+if (fs.exists(appPath)) {
+  await fs.ls(appPath)
+} else {
+  await fs.mkdir(appPath)
+}
+```
+
+
 ## Basics
@@ -93,90 +105,16 @@
 - `cat`: retrieve a file
+- `exists`: check if a file or directory exists
 - `ls`: list a directory
 - `mkdir`: create a directory
 - `mv`: move a file or directory
+- `read`: alias for `cat`
 - `rm`: remove a file or directory
+- `write`: write to a file
 
 
-## Versions
-
-Since the file system may evolve over time, a "version" is associated with each node in the file system (tracked with semver).
-
-Currently two versions exist:
-- `1.0.0`: file tree with metadata. Nodes in the file tree are structured as 2 layers where one layer contains "header" information (metadata, cache, etc), and the second layer contains data or links. **This is the default version, use this unless you have a good reason not to**.
-- `0.0.0`: bare file tree. The public tree consists of [ipfs dag-pg](https://github.com/ipld/js-ipld-dag-pb) nodes. The private tree is encrypted links with no associated metadata. These should really only be used for vanity links to be rendered by a gateway.
-
-
 ## API
 
-### Config
-
-Each instantiation method takes an optional config. Below is the default config and descriptions of each value.
-
-```ts
-const defaultConfig = {
-  keyName: 'filesystem-root', // the name of the key for the filesystem root as stored in IndexedDB
-  version: '1.0.0' // the version of the filesystem as discussed above
-}
-```
----
-
-### Instantiation
-
-**empty**
-
-Creates a file system with an empty public tree & an empty private tree at the root
-
-Params:
-- cfg: `FileSystemConfig` _optional_
-
-Returns: `FileSystem` instance
-
-Example:
-```ts
-import FileSystem from 'fission-sdk/fs'
-const wnfs = await FileSystem.empty()
-```
-
----
-
-**fromCID**
-
-Loads an existing file system from a CID
-
-Params:
-- cid: `CID` (`string`) **required**
-- cfg: `FileSystemConfig` _optional_
-
-Returns: `FileSystem` instance
-
-Example:
-```ts
-import FileSystem from 'fission-sdk/fs'
-const cid = "QmWKst5WVNTPfMsSFCQEJYBJLEsUZfghqrKXJBVU4EuA76"
-const wnfs = await FileSystem.fromCID(cid)
-```
-
----
-
-**forUser**
-
-Loads an existing file system from a username
-
-Params:
-- username: `string` **required**
-- cfg: `FileSystemConfig` _optional_
-
-Returns: `FileSystem` instance
-
-Example:
-```ts
-import FileSystem from 'fission-sdk/fs'
-const wnfs = await FileSystem.forUser("boris")
-```
-
----
-
 ### Methods
 
-Methods for interacting with the filesystem all use **absolute** paths. We're planning on adding a [stateful session](https://github.com/fission-suite/ts-sdk/issues/24) but for now, filesystem state will need to be tracked in your application.
+Methods for interacting with the filesystem all use **absolute** paths.
 
@@ -218,2 +156,18 @@ **add**
 
+**exists**
+
+Checks if there is anything located at a given path
+
+Params:
+- path: `string` **required**
+
+Returns: `boolean`
+
+Example:
+```ts
+const bool = await wnfs.exists("private/path/to/file")
+```
+
+---
+
 **get**
@@ -242,10 +196,20 @@
 
-Returns: `Links[]` list of links
+Returns: `{ [name: string]: Link }` Object with the file name as the key and its `Link` as the value.
 
 Example:
 ```ts
-// public
-const links = await wnfs.ls("public/some/directory/path")
-// private
-const links = await wnfs.ls("private/some/directory/path")
+linksObject = await wnfs.ls("public/some/directory/path") // public
+linksObject = await wnfs.ls("private/some/directory/path") // private
+
+// convert to list
+links = Object.entries(linksObject)
+
+// working with links
+data = await Promise.all(links.map(([name, _]) => {
+  return fs.cat(`private/some/directory/path/${name}`)
+}))
+
+
+
+
 ```
@@ -289,13 +253,14 @@
 
-**pinList**
+**rm**
 
-Retrieves an array of all CIDs that need to be pinned in order to backup the FS
+Removes a file or directory at a given path
 
-Params: _none_
+Params:
+- path: `string` **required**
 
-Returns: `CID[]`
+Returns: `CID` the updated _root_ CID for the file system
 
 Example:
 ```ts
-const allCIDs = await wnfs.pinList()
+const updatedCID = await wnfs.rm("private/some/path/to/a/file")
 ```
@@ -305,8 +270,10 @@
 
-**rm**
+**write**
 
-Removes a file or directory at a given path
+Write to a file at a given path.
+Overwrites existing content.
 
 Params:
 - path: `string` **required**
+- content: `FileContent` (`object | string | Blob | Buffer`) **required**
 
@@ -317,22 +284,32 @@ Returns: `CID` the updated _root_ CID for the file system
 ```ts
-const updatedCID = await wnfs.rm("private/some/path/to/a/file")
+const content = "hello world"
+const updatedCID = await wnfs.write("public/some/path/to/a/file", content)
 ```
 
----
 
-**sync**
+## Web Worker
 
-Ensures the latest version of the file system is added to IPFS and returns the root CID
+Can I use my file system in a web worker?  
+Yes, this only requires a slightly different setup.
 
-Params: _none_
+```ts
+// UI thread
+// `session.fs` will now be `null`
+sdk.isAuthenticated({ loadFileSystem: false })
 
-Returns: `CID` the updated _root_ CID for the file system
-
-Example:
-```ts
-const rootCID = await wnfs.sync()
+// Web Worker
+const fs = await sdk.loadFileSystem()
 ```
 
 
+## Versions
 
+Since the file system may evolve over time, a "version" is associated with each node in the file system (tracked with semver).
+
+Currently two versions exist:
+- `1.0.0`: file tree with metadata. Nodes in the file tree are structured as 2 layers where one layer contains "header" information (metadata, cache, etc), and the second layer contains data or links. **This is the default version, use this unless you have a good reason not to**.
+- `0.0.0`: bare file tree. The public tree consists of [ipfs dag-pg](https://github.com/ipld/js-ipld-dag-pb) nodes. The private tree is encrypted links with no associated metadata. These should really only be used for vanity links to be rendered by a gateway.
+
+
+
 # Customisation
@@ -339,0 +316,0 @@

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

8980379

increased by4151.87%

Dependency count

8

decreased by-11.11%

Number of package files

162

increased by60.4%

Lines of code

88763

increased by2490.11%

Worsened metrics

Number of lines in readme file

380

decreased by-5.71%

Number of medium supply chain risk alerts

18

increased by1700%

Dependency changes

• - Removedbloomfilter@^0.0.18

• - Removedbloomfilter@0.0.18(transitive)