jsonjsdb 0.1.0__tar.gz

jsonjsdb-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.egg-info/
+.venv/
+.ruff_cache/
+.pytest_cache/
+uv.lock
+
+# Coverage
+htmlcov/
+.coverage
+coverage.xml

jsonjsdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026-present Bassim Matar - datannur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

jsonjsdb-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: jsonjsdb
+Version: 0.1.0
+Summary: Python library for JSONJS database loading
+Project-URL: Homepage, https://github.com/datannur/jsonjsdb
+Project-URL: Repository, https://github.com/datannur/jsonjsdb
+Project-URL: Documentation, https://github.com/datannur/jsonjsdb#readme
+Project-URL: Issues, https://github.com/datannur/jsonjsdb/issues
+Author: datannur
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Requires-Dist: polars>=1.0.0
+Description-Content-Type: text/markdown
+
+# jsonjsdb
+
+[![PyPI version](https://img.shields.io/pypi/v/jsonjsdb.svg)](https://pypi.org/project/jsonjsdb/)
+[![Python](https://img.shields.io/badge/python-≥3.9-blue.svg)](https://pypi.org/project/jsonjsdb/)
+[![CI](https://github.com/datannur/jsonjsdb/actions/workflows/ci.yml/badge.svg)](https://github.com/datannur/jsonjsdb/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/datannur/jsonjsdb/branch/main/graph/badge.svg?flag=python)](https://codecov.io/gh/datannur/jsonjsdb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python library for JSONJS databases with full CRUD support and relational queries.
+
+## Features
+
+- **Read & Write**: Full CRUD operations
+- **Typed API**: Optional TypedDict support with autocompletion
+- **Relational queries**: `having.{table}(id)` for one-to-many and many-to-many
+- **Filtering**: `where()` with operators (`==`, `!=`, `>`, `in`, `is_null`, etc.)
+- **TypeScript compatible**: Same file format as the TypeScript jsonjsdb library
+
+## Installation
+
+```bash
+pip install jsonjsdb
+```
+
+## Quick Start
+
+```python
+from jsonjsdb import Jsonjsdb
+
+db = Jsonjsdb("path/to/db")
+
+# Read
+user = db["user"].get("user_1")
+active = db["user"].where("status", "==", "active")
+
+# Write
+db["user"].add({"id": "u1", "name": "Alice", "tag_ids": []})
+db["user"].update("u1", name="Alice Updated")
+db.save()
+```
+
+## Typed Access
+
+```python
+from typing import TypedDict
+from jsonjsdb import Jsonjsdb, Table
+
+class User(TypedDict):
+    id: str
+    name: str
+    tag_ids: list[str]
+
+class MyDB(Jsonjsdb):
+    user: Table[User]
+
+db = MyDB("path/to/db")
+user = db.user.get("user_1")  # Returns User | None (with autocompletion)
+```
+
+## API Reference
+
+### CRUD
+
+```python
+db.user.add({"id": "u1", "name": "Alice", ...})  # Add row (id required)
+db.user.add_all([...])                           # Add multiple rows
+
+db.user.get("u1")                                # → User | None
+db.user.all()                                    # → list[User]
+
+db.user.update("u1", name="New Name")            # Update fields
+db.user.remove("u1")                             # → bool
+db.user.remove_all(["u1", "u2"])                 # → int (count)
+```
+
+### Filtering
+
+```python
+db.user.where("status", "==", "active")          # Equality
+db.user.where("age", ">", 18)                    # Comparison (>, >=, <, <=)
+db.user.where("status", "in", ["a", "b"])        # In list
+db.user.where("email", "is_null")                # Null check (is_not_null)
+```
+
+### Relations
+
+```python
+db.email.having.user("user_1")      # One-to-many: where user_id == "user_1"
+db.user.having.tag("tag_1")         # Many-to-many: where tag_ids contains "tag_1"
+db.folder.having.parent("folder_1") # Hierarchy: where parent_id == "folder_1"
+```
+
+### Save / New Database
+
+```python
+db.save()                # Save to original path
+db.save("new/path")      # Save to new location
+
+db = MyDB()              # Create empty in-memory DB
+db.user.add({...})
+db.save("path/to/db")    # Path required on first save
+```
+
+## File Format
+
+- `__table__.json` — Index of tables with metadata
+- `{table}.json` — Data as array of objects
+- `{table}.json.js` — Same data for browser (JavaScript)
+
+### Column Conventions
+
+| Column | Description |
+|--------|-------------|
+| `id` | Primary key (always string) |
+| `xxx_id` | Foreign key to table `xxx` |
+| `xxx_ids` | Many-to-many (comma-separated in file, `list[str]` in API) |
+| `parent_id` | Self-reference for hierarchies |
+
+## License
+
+MIT

jsonjsdb-0.1.0/README.md

@@ -0,0 +1,121 @@
+# jsonjsdb
+
+[![PyPI version](https://img.shields.io/pypi/v/jsonjsdb.svg)](https://pypi.org/project/jsonjsdb/)
+[![Python](https://img.shields.io/badge/python-≥3.9-blue.svg)](https://pypi.org/project/jsonjsdb/)
+[![CI](https://github.com/datannur/jsonjsdb/actions/workflows/ci.yml/badge.svg)](https://github.com/datannur/jsonjsdb/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/datannur/jsonjsdb/branch/main/graph/badge.svg?flag=python)](https://codecov.io/gh/datannur/jsonjsdb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python library for JSONJS databases with full CRUD support and relational queries.
+
+## Features
+
+- **Read & Write**: Full CRUD operations
+- **Typed API**: Optional TypedDict support with autocompletion
+- **Relational queries**: `having.{table}(id)` for one-to-many and many-to-many
+- **Filtering**: `where()` with operators (`==`, `!=`, `>`, `in`, `is_null`, etc.)
+- **TypeScript compatible**: Same file format as the TypeScript jsonjsdb library
+
+## Installation
+
+```bash
+pip install jsonjsdb
+```
+
+## Quick Start
+
+```python
+from jsonjsdb import Jsonjsdb
+
+db = Jsonjsdb("path/to/db")
+
+# Read
+user = db["user"].get("user_1")
+active = db["user"].where("status", "==", "active")
+
+# Write
+db["user"].add({"id": "u1", "name": "Alice", "tag_ids": []})
+db["user"].update("u1", name="Alice Updated")
+db.save()
+```
+
+## Typed Access
+
+```python
+from typing import TypedDict
+from jsonjsdb import Jsonjsdb, Table
+
+class User(TypedDict):
+    id: str
+    name: str
+    tag_ids: list[str]
+
+class MyDB(Jsonjsdb):
+    user: Table[User]
+
+db = MyDB("path/to/db")
+user = db.user.get("user_1")  # Returns User | None (with autocompletion)
+```
+
+## API Reference
+
+### CRUD
+
+```python
+db.user.add({"id": "u1", "name": "Alice", ...})  # Add row (id required)
+db.user.add_all([...])                           # Add multiple rows
+
+db.user.get("u1")                                # → User | None
+db.user.all()                                    # → list[User]
+
+db.user.update("u1", name="New Name")            # Update fields
+db.user.remove("u1")                             # → bool
+db.user.remove_all(["u1", "u2"])                 # → int (count)
+```
+
+### Filtering
+
+```python
+db.user.where("status", "==", "active")          # Equality
+db.user.where("age", ">", 18)                    # Comparison (>, >=, <, <=)
+db.user.where("status", "in", ["a", "b"])        # In list
+db.user.where("email", "is_null")                # Null check (is_not_null)
+```
+
+### Relations
+
+```python
+db.email.having.user("user_1")      # One-to-many: where user_id == "user_1"
+db.user.having.tag("tag_1")         # Many-to-many: where tag_ids contains "tag_1"
+db.folder.having.parent("folder_1") # Hierarchy: where parent_id == "folder_1"
+```
+
+### Save / New Database
+
+```python
+db.save()                # Save to original path
+db.save("new/path")      # Save to new location
+
+db = MyDB()              # Create empty in-memory DB
+db.user.add({...})
+db.save("path/to/db")    # Path required on first save
+```
+
+## File Format
+
+- `__table__.json` — Index of tables with metadata
+- `{table}.json` — Data as array of objects
+- `{table}.json.js` — Same data for browser (JavaScript)
+
+### Column Conventions
+
+| Column | Description |
+|--------|-------------|
+| `id` | Primary key (always string) |
+| `xxx_id` | Foreign key to table `xxx` |
+| `xxx_ids` | Many-to-many (comma-separated in file, `list[str]` in API) |
+| `parent_id` | Self-reference for hierarchies |
+
+## License
+
+MIT

jsonjsdb-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jsonjsdb"
+version = "0.1.0"
+description = "Python library for JSONJS database loading"
+authors = [{ name = "datannur" }]
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = ["polars>=1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/datannur/jsonjsdb"
+Repository = "https://github.com/datannur/jsonjsdb"
+Documentation = "https://github.com/datannur/jsonjsdb#readme"
+Issues = "https://github.com/datannur/jsonjsdb/issues"
+
+[dependency-groups]
+dev = [
+  "pytest",
+  "pytest-cov",
+  "ruff",
+  "pyright>=1.1.400",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jsonjsdb"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/jsonjsdb"]
+
+[tool.pyright]
+pythonVersion = "3.9"
+typeCheckingMode = "standard"
+
+[tool.coverage.run]
+source = ["src/jsonjsdb"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:", "@overload", "\\.\\.\\."]

jsonjsdb-0.1.0/src/jsonjsdb/__init__.py

@@ -0,0 +1,10 @@
+"""JSONJS database library for Python."""
+
+from importlib.metadata import version
+
+from .database import Jsonjsdb
+from .table import Table
+from .types import ID, Operator, TableRow
+
+__version__ = version("jsonjsdb")
+__all__ = ["Jsonjsdb", "Table", "ID", "Operator", "TableRow"]

jsonjsdb-0.1.0/src/jsonjsdb/database.py

@@ -0,0 +1,111 @@
+"""Main Jsonjsdb database class."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, get_type_hints
+
+from .loader import load_table, load_table_index
+from .table import Table
+from .types import TableRow
+from .writer import write_table_index, write_table_json, write_table_jsonjs
+
+
+class Jsonjsdb:
+    """JSONJS database with typed table access.
+
+    Usage (untyped):
+        db = Jsonjsdb("path/to/db")
+        user = db["user"].get("user_1")
+
+    Usage (typed):
+        class MyDB(Jsonjsdb):
+            user: Table[User]
+            tag: Table[Tag]
+
+        db = MyDB("path/to/db")
+        user = db.user.get("user_1")  # Typed as User | None
+    """
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        self._path: Path | None = Path(path) if path else None
+        self._tables: dict[str, Table[Any]] = {}
+
+        if self._path:
+            self._load_from_path(self._path)
+
+        self._init_typed_tables()
+
+    def _load_from_path(self, path: Path) -> None:
+        """Load all tables from disk."""
+        if not path.exists():
+            raise FileNotFoundError(f"Database path does not exist: {path}")
+
+        table_index_path = path / "__table__.json"
+        if not table_index_path.exists():
+            raise FileNotFoundError(f"Missing __table__.json in {path}")
+
+        table_index = load_table_index(table_index_path)
+
+        for entry in table_index:
+            name = str(entry["name"])
+            json_path = path / f"{name}.json"
+
+            if json_path.exists():
+                df = load_table(json_path)
+                self._tables[name] = Table(name, self, df)
+
+    def _init_typed_tables(self) -> None:
+        """Initialize Table attributes from type annotations on subclasses."""
+        hints = get_type_hints(self.__class__)
+
+        for attr_name, hint in hints.items():
+            origin = getattr(hint, "__origin__", None)
+            if origin is Table:
+                if attr_name in self._tables:
+                    setattr(self, attr_name, self._tables[attr_name])
+                else:
+                    table = Table(attr_name, self)
+                    self._tables[attr_name] = table
+                    setattr(self, attr_name, table)
+
+    def __getitem__(self, table_name: str) -> Table[TableRow]:
+        """Access a table by name (untyped)."""
+        if table_name not in self._tables:
+            raise KeyError(f"Table '{table_name}' not found")
+        return self._tables[table_name]
+
+    @property
+    def path(self) -> Path | None:
+        return self._path
+
+    @property
+    def tables(self) -> list[str]:
+        """List of loaded table names."""
+        return list(self._tables.keys())
+
+    def save(self, path: str | Path | None = None) -> None:
+        """Save all tables to disk.
+
+        If path is provided, saves to that location and updates self._path.
+        If path is None, saves to the original path (must exist).
+        """
+        save_path = Path(path) if path else self._path
+
+        if save_path is None:
+            raise ValueError(
+                "No path specified. Provide a path or load from an existing database first."
+            )
+
+        save_path.mkdir(parents=True, exist_ok=True)
+
+        table_names = []
+        for name, table in self._tables.items():
+            if not table.df.is_empty():
+                write_table_json(table.df, save_path / f"{name}.json")
+                write_table_jsonjs(table.df, name, save_path / f"{name}.json.js")
+                table_names.append(name)
+
+        write_table_index(table_names, save_path / "__table__.json")
+
+        self._path = save_path

jsonjsdb-0.1.0/src/jsonjsdb/loader.py

@@ -0,0 +1,55 @@
+"""Load JSON files into Polars DataFrames."""
+
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+
+def load_table(path: Path) -> pl.DataFrame:
+    """Load a JSON file into a Polars DataFrame.
+
+    - Converts 'id' column to string type
+    - Converts '*_ids' columns from comma-separated strings to list[str]
+    """
+    df = pl.read_json(path)
+
+    if df.is_empty():
+        return df
+
+    transforms: list[pl.Expr] = []
+
+    for col_name in df.columns:
+        col_type = df.schema[col_name]
+
+        if col_name == "id":
+            transforms.append(pl.col("id").cast(pl.Utf8).alias("id"))
+        elif col_name.endswith("_ids"):
+            transforms.append(_convert_ids_column(col_name, col_type))
+        else:
+            transforms.append(pl.col(col_name))
+
+    return df.select(transforms)
+
+
+def _convert_ids_column(col_name: str, col_type: pl.DataType) -> pl.Expr:
+    """Convert a *_ids column from comma-separated string to list[str]."""
+    col = pl.col(col_name)
+
+    if col_type == pl.Utf8 or col_type == pl.String:
+        return (
+            pl.when(col.is_null() | (col == ""))
+            .then(pl.lit([]).cast(pl.List(pl.Utf8)))
+            .otherwise(col.str.split(","))
+            .alias(col_name)
+        )
+
+    return col
+
+
+def load_table_index(path: Path) -> list[dict[str, Any]]:
+    """Load __table__.json which contains table metadata."""
+    import json
+
+    with open(path) as f:
+        return json.load(f)

jsonjsdb-0.1.0/src/jsonjsdb/table.py

@@ -0,0 +1,227 @@
+"""Table class wrapping a Polars DataFrame."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload
+
+import polars as pl
+
+from .types import ID, Operator
+
+if TYPE_CHECKING:
+    from .database import Jsonjsdb
+
+T = TypeVar("T")
+
+
+class Table(Generic[T]):
+    """A table backed by a Polars DataFrame."""
+
+    def __init__(
+        self,
+        name: str,
+        db: Jsonjsdb | None = None,
+        df: pl.DataFrame | None = None,
+    ) -> None:
+        self._name = name
+        self._db = db
+        self._df = df if df is not None else pl.DataFrame()
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def df(self) -> pl.DataFrame:
+        return self._df
+
+    @property
+    def having(self) -> HavingProxy[T]:
+        """Access relational queries via having.{table}(id)."""
+        if self._db is None:
+            raise RuntimeError("Cannot use 'having' without a database context")
+        return HavingProxy(self, self._db)
+
+    def get(self, id: ID) -> T | None:
+        """Get a single row by ID, or None if not found."""
+        result = self._df.filter(pl.col("id") == id)
+        if result.is_empty():
+            return None
+        return self._row_to_dict(result.row(0, named=True))
+
+    def all(self) -> list[T]:
+        """Get all rows as a list of dicts."""
+        return [self._row_to_dict(row) for row in self._df.iter_rows(named=True)]
+
+    @overload
+    def where(self, column: str, op: Operator, value: Any) -> list[T]: ...
+
+    @overload
+    def where(self, column: str, op: Operator) -> list[T]: ...
+
+    def where(self, column: str, op: Operator, value: Any = None) -> list[T]:
+        """Filter rows by a condition.
+
+        Operators: ==, !=, >, >=, <, <=, in, is_null, is_not_null
+        """
+        col = pl.col(column)
+        expr: pl.Expr
+
+        if op == "==":
+            expr = col == value
+        elif op == "!=":
+            expr = col != value
+        elif op == ">":
+            expr = col > value
+        elif op == ">=":
+            expr = col >= value
+        elif op == "<":
+            expr = col < value
+        elif op == "<=":
+            expr = col <= value
+        elif op == "in":
+            expr = col.is_in(value)
+        elif op == "is_null":
+            expr = col.is_null()
+        elif op == "is_not_null":
+            expr = col.is_not_null()
+        else:
+            raise ValueError(f"Unknown operator: {op}")
+
+        result = self._df.filter(expr)
+        return [self._row_to_dict(row) for row in result.iter_rows(named=True)]
+
+    def _row_to_dict(self, row: dict[str, Any]) -> T:
+        """Convert a Polars row dict to API dict (T)."""
+        return row  # type: ignore[return-value]
+
+    # --- CRUD operations ---
+
+    def add(self, row: T) -> None:
+        """Add a single row. Raises ValueError if id missing or already exists."""
+        row_dict: dict[str, Any] = row  # type: ignore[assignment]
+
+        if "id" not in row_dict:
+            raise ValueError("Row must have an 'id' field")
+
+        row_id = str(row_dict["id"])
+        if (
+            not self._df.is_empty()
+            and not self._df.filter(pl.col("id") == row_id).is_empty()
+        ):
+            raise ValueError(f"Row with id '{row_id}' already exists")
+
+        prepared = self._prepare_row_for_storage(row_dict)
+        new_df = pl.DataFrame([prepared])
+
+        if self._df.is_empty():
+            self._df = new_df
+        else:
+            self._df = pl.concat([self._df, new_df], how="diagonal")
+
+    def add_all(self, rows: list[T]) -> None:
+        """Add multiple rows."""
+        for row in rows:
+            self.add(row)
+
+    def update(self, id: ID, **kwargs: Any) -> None:
+        """Update a row by ID. Raises KeyError if not found."""
+        if self._df.is_empty() or self._df.filter(pl.col("id") == id).is_empty():
+            raise KeyError(f"Row with id '{id}' not found")
+
+        updates: list[pl.Expr] = []
+        for col_name in self._df.columns:
+            if col_name in kwargs:
+                value = kwargs[col_name]
+                updates.append(
+                    pl.when(pl.col("id") == id)
+                    .then(pl.lit(value, allow_object=True))
+                    .otherwise(pl.col(col_name))
+                    .alias(col_name)
+                )
+            else:
+                updates.append(pl.col(col_name))
+
+        self._df = self._df.select(updates)
+
+    def remove(self, id: ID) -> bool:
+        """Remove a row by ID. Returns True if removed, False if not found."""
+        if self._df.is_empty():
+            return False
+
+        original_len = len(self._df)
+        self._df = self._df.filter(pl.col("id") != id)
+        return len(self._df) < original_len
+
+    def remove_all(self, ids: list[ID]) -> int:
+        """Remove multiple rows by ID. Returns count of removed rows."""
+        if self._df.is_empty():
+            return 0
+
+        original_len = len(self._df)
+        self._df = self._df.filter(~pl.col("id").is_in(ids))
+        return original_len - len(self._df)
+
+    def _prepare_row_for_storage(self, row: dict[str, Any]) -> dict[str, Any]:
+        """Prepare row for internal DataFrame storage.
+
+        - Converts id to string
+        - Keeps *_ids as lists (DataFrame stores them as List(String))
+        """
+        prepared = {}
+        for key, value in row.items():
+            if key == "id":
+                prepared[key] = str(value)
+            else:
+                prepared[key] = value
+        return prepared
+
+
+class HavingProxy(Generic[T]):
+    """Proxy for relational queries: table.having.{target}(id).
+
+    Detects relation type automatically:
+    - If {target}_id exists → one-to-many (filter by foreign key)
+    - If {target}_ids exists → many-to-many (filter by list contains)
+    - Special case: 'parent' → looks for parent_id (self-reference)
+    """
+
+    def __init__(self, table: Table[T], db: Jsonjsdb) -> None:
+        self._table = table
+        self._db = db
+
+    def __getattr__(self, target: str) -> _RelationQuery[T]:
+        return _RelationQuery(self._table, self._db, target)
+
+
+class _RelationQuery(Generic[T]):
+    """Callable that executes the relation query."""
+
+    def __init__(self, table: Table[T], db: Jsonjsdb, target: str) -> None:
+        self._table = table
+        self._db = db
+        self._target = target
+
+    def __call__(self, id: ID) -> list[T]:
+        columns = self._table.df.columns
+
+        # Special case: 'parent' → parent_id (self-reference)
+        lookup_target = "parent" if self._target == "parent" else self._target
+
+        # Check for {target}_id (one-to-many)
+        fk_col = f"{lookup_target}_id"
+        if fk_col in columns:
+            return self._table.where(fk_col, "==", id)
+
+        # Check for {target}_ids (many-to-many)
+        fk_ids_col = f"{lookup_target}_ids"
+        if fk_ids_col in columns:
+            result = self._table.df.filter(pl.col(fk_ids_col).list.contains(id))
+            return [
+                self._table._row_to_dict(row) for row in result.iter_rows(named=True)
+            ]
+
+        raise AttributeError(
+            f"No relation '{self._target}' found in table '{self._table.name}'. "
+            f"Expected column '{fk_col}' or '{fk_ids_col}'."
+        )

jsonjsdb-0.1.0/src/jsonjsdb/types.py

@@ -0,0 +1,9 @@
+"""Type definitions for jsonjsdb."""
+
+from typing import Any, Literal
+
+ID = str
+
+TableRow = dict[str, Any]
+
+Operator = Literal["==", "!=", ">", ">=", "<", "<=", "in", "is_null", "is_not_null"]

jsonjsdb-0.1.0/src/jsonjsdb/writer.py

@@ -0,0 +1,71 @@
+"""Write Polars DataFrames to JSON and JSON.js files."""
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+
+def write_table_json(df: pl.DataFrame, path: Path) -> None:
+    """Write a DataFrame to a JSON file (array of objects)."""
+    prepared_df = _prepare_df_for_write(df)
+    rows = _df_to_json_rows(prepared_df)
+    with open(path, "w") as f:
+        json.dump(rows, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def write_table_jsonjs(df: pl.DataFrame, table_name: str, path: Path) -> None:
+    """Write a DataFrame to a JSON.js file (array of arrays format)."""
+    prepared_df = _prepare_df_for_write(df)
+    columns = prepared_df.columns
+    rows: list[list[Any]] = [columns]
+
+    for row in prepared_df.iter_rows():
+        rows.append(list(row))
+
+    json_array = json.dumps(rows, ensure_ascii=False, separators=(",", ":"))
+    content = f"jsonjs.data['{table_name}'] = {json_array}\n"
+
+    with open(path, "w") as f:
+        f.write(content)
+
+
+def write_table_index(tables: list[str], path: Path) -> None:
+    """Write __table__.json with table metadata."""
+    now = int(time.time())
+    entries = [{"name": name, "last_modif": now} for name in sorted(tables)]
+
+    with open(path, "w") as f:
+        json.dump(entries, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def _prepare_df_for_write(df: pl.DataFrame) -> pl.DataFrame:
+    """Prepare DataFrame for writing: convert List columns to comma-separated strings."""
+    transforms: list[pl.Expr] = []
+
+    for col_name in df.columns:
+        col_type = df.schema[col_name]
+        if isinstance(col_type, pl.List):
+            transforms.append(
+                pl.col(col_name)
+                .cast(pl.List(pl.Utf8))
+                .list.join(",")
+                .fill_null("")
+                .alias(col_name)
+            )
+        else:
+            transforms.append(pl.col(col_name))
+
+    return df.select(transforms)
+
+
+def _df_to_json_rows(df: pl.DataFrame) -> list[dict[str, Any]]:
+    """Convert DataFrame to list of dicts for JSON serialization."""
+    rows = []
+    for row in df.iter_rows(named=True):
+        rows.append(row)
+    return rows