Metadata-Version: 2.4
Name: jsondocstore
Version: 0.1.0
Summary: Simple JSON document storage on disk
Author-email: Mirko Ortensi <mirko.ortensi@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# JsonDocStore

Simple JSON document storage on disk.

Each document is stored as one file named `<key>.json`. The document key is the filename stem, not a field inside the JSON body.

If you want to organize documents into different folders, use one `JsonDocStore` instance per folder. Each instance manages only the JSON files in its own directory.

## What It Does

- Stores one JSON document per file.
- Reads documents directly by filename.
- Uses optional in-memory indexes defined in `index.json`.
- Provides an interactive CLI in `cli.py`.

## Data Model

- `get(key)` reads `<key>.json`.
- `insert(key, doc)` writes `<key>.json`.
- Valid keys may contain letters, digits, `.`, `_`, and `-`. No whitespace.

## Schema

`index.json` is optional.

- `create=True` creates the directory if needed. It does not create `index.json`.
- `index_fields` defines which fields are indexed in memory.
- `get()`, `insert()`, `delete()`, and `list_all()` work without `index.json`.
- `query_by()` only works when an index exists. Querying without an index, or on a non-indexed field, raises an error.
- Indexes work only on top-level document fields, not nested paths.

Example:

```json
{
  "index_fields": ["email", "status"]
}
```

For example, this works:

```json
{
  "email": "alice@example.com",
  "profile": {
    "city": "Rome"
  }
}
```

- you can index `email`
- you cannot index `profile.city`

## CLI

Start the interactive shell:

```bash
jsondocstore /path/to/store
```

Commands:

- `list` prints document filenames only
- `listindexes` prints indexed fields, or `[]` if there is no `index.json`
- `queryby FIELD VALUE`
- `createindex FIELD`
- `deleteindex FIELD`
- `insert KEY JSON_DOCUMENT`
- `update KEY JSON_DOCUMENT`
- `delete KEY`
- `exit`

Example session:

```text
$ jsondocstore ./data
jsondocstore> insert user-1 '{"username": "alice", "password": "secret1", "role": "admin"}'
jsondocstore> insert user-2 '{"username": "bob", "password": "secret2", "role": "user"}'
jsondocstore> insert user-3 '{"username": "carol", "password": "secret3", "role": "user"}'
jsondocstore> update user-2 '{"username": "bob", "password": "secret2", "role": "admin"}'
jsondocstore> list
[
  "user-1.json",
  "user-2.json",
  "user-3.json"
]
jsondocstore> createindex role
jsondocstore> queryby role user
[
  {
    "password": "secret2",
    "role": "user",
    "username": "bob"
  },
  {
    "password": "secret3",
    "role": "user",
    "username": "carol"
  }
]
```

## Library

```python
from jsondocstore import JsonDocStore

store = JsonDocStore("./data", create=True)
store.insert("user-1", {"username": "alice", "password": "secret1", "role": "admin"})
store.insert("user-2", {"username": "bob", "password": "secret2", "role": "user"})
store.insert("user-3", {"username": "carol", "password": "secret3", "role": "user"})
store.update("user-2", {"username": "bob", "password": "secret2", "role": "admin"})
names = store.list_all()
store.create_index("role")
admins = store.query_by("role", "admin")
doc = store.get("user-1")
```
