Update README

.eslintrc.json

@@ -37,7 +37,9 @@
     "jsdoc/check-property-names": "error",
     "jsdoc/check-tag-names": "error",
     "jsdoc/sort-tags": "error",
+    "jsdoc/require-param": "error",
     "jsdoc/require-param-type": "error",
+    "jsdoc/require-returns": "error",
     "jsdoc/require-returns-type": "error",
     "no-multi-spaces": "error",
     "no-trailing-spaces": "error",

README.md

@@ -2,9 +2,10 @@
 
 ![hyllama](hyllama.jpg)
 
-[![mit license](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![workflow status](https://github.com/hyparam/hyllama/actions/workflows/ci.yml/badge.svg)](https://github.com/hyparam/hyllama/actions)
 [![npm](https://img.shields.io/npm/v/hyllama)](https://www.npmjs.com/package/hyllama)
+[![workflow status](https://github.com/hyparam/hyllama/actions/workflows/ci.yml/badge.svg)](https://github.com/hyparam/hyllama/actions)
+[![mit license](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![dependencies](https://img.shields.io/badge/Dependencies-0-blueviolet)
 
 Javascript parser for [llama.cpp](https://github.com/ggerganov/llama.cpp) gguf files.
 
@@ -21,18 +22,39 @@ A goal of this library is to parse the file efficiently, without loading the ent
 
 Dependency free since 2023!
 
-## Usage
+## Installation
 
 ```bash
 npm install hyllama
 ```
 
+## Usage
+
+If you're in a node.js environment, you can load a .gguf file with the following example:
+
+```js
+const { ggufMetadata } = await import('hyllama')
+const fs = await import('fs')
+
+const buffer = fs.readFileSync('example.gguf')
+const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength)
+const metadata = ggufMetadata(arrayBuffer)
+```
+
+If you're in a browser environment, you'll probably get parquet file data from either a drag-and-dropped file from the user, or downloaded from the web.
+
+To load parquet data in the browser from a remote server using `fetch`:
+
 ```js
 import { ggufMetadata } from 'hyllama'
 
+const res = await fetch(url)
+const arrayBuffer = await res.arrayBuffer()
 const metadata = ggufMetadata(arrayBuffer)
 ```
 
+To parse .gguf files from a user drag-and-drop action, see example in [index.html](index.html).
+
 ## References
 
  - https://github.com/ggerganov/llama.cpp

index.html

@@ -45,7 +45,7 @@
       })
 
       dropZone.addEventListener('drop', e => {
-        e.preventDefault() // prevent file from being downloaded
+        e.preventDefault() // prevent dropped file from being "downloaded"
         dropZone.classList.remove('over')
 
         const files = e.dataTransfer.files

package.json

@@ -22,7 +22,7 @@
   "types": "src/hyllama.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/hyparam/hyllama"
+    "url": "git+https://github.com/hyparam/hyllama.git"
   },
   "scripts": {
     "coverage": "vitest run --coverage",
@@ -32,12 +32,12 @@
     "typecheck": "tsc"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "1.1.1",
+    "@vitest/coverage-v8": "1.1.3",
     "eslint": "8.56.0",
     "eslint-plugin-import": "2.29.1",
     "eslint-plugin-jsdoc": "48.0.2",
     "http-server": "14.1.1",
     "typescript": "5.3.3",
-    "vitest": "1.1.1"
+    "vitest": "1.1.3"
   }
 }

src/hyllama.js

@@ -1,9 +1,6 @@
 /**
  * Read llama.cpp GGUF metadata from a file
  *
- * Decoded is an object with newOffset and value properties
- *
- * @typedef {{ newOffset: number, value: any }} Decoded
  * @param {ArrayBuffer} arrayBuffer gguf file contents
  * @returns {Record<string, any>} metadata object
  */
@@ -27,6 +24,10 @@ export function ggufMetadata(arrayBuffer) {
 
   /**
    * Helper function to read metadata value based on type
+   *
+   * Decoded is an object with newOffset and value properties
+   *
+   * @typedef {{ newOffset: number, value: any }} Decoded
    * @param {number} type
    * @param {number} offset
    * @returns {Decoded}