@elek-io/core 0.16.2 → 0.17.0

package/README.md

@@ -2,13 +2,36 @@
 
 [![codecov](https://codecov.io/gh/elek-io/core/graph/badge.svg?token=GSZIZMVG6Q)](https://codecov.io/gh/elek-io/core)
 
-Handles core functionality of elek.io Projects like file IO and version control as well as providing schemas and types.
+Handles core functionality of elek.io Projects like file IO and version control as well as providing schemas, types and a local REST API.
+
+## Installation
+
+```bash
+npm install @elek-io/core
+```
+
+## Exports
+
+The package provides multiple entry points for different environments:
+
+- **Node** (`@elek-io/core`) — The `ElekIoCore` main class with full access to services, API, schemas and utilities.
+- **Browser** (`@elek-io/core`) — All schemas and types but without the `ElekIoCore` class, since it is not usable in a browser environment.
+- **Astro** (`@elek-io/core/astro`) — Astro content loaders `elekAssets()` and `elekEntries()` for loading Project data into Astro.
+- **CLI** (`elek`) — A command-line interface with commands for generating API clients, starting a local API and exporting Projects.
+
+## Source structure
 
 ```
 |-- src
 |   |-- api
-|   |   Exports a local API that allows reading Project data
-|   |   mainly for development of websites or apps on the same device.
+|   |   Local REST API built on Hono with OpenAPI documentation.
+|   |   Provides routes for Projects, Collections, Entries and Assets.
+|   |-- astro
+|   |   Astro integration with content loaders and dynamic schema building
+|   |   based on Collection Field definitions.
+|   |-- cli
+|   |   Command-line interface with commands:
+|   |   generate:client, api:start and export.
 |   |-- error
 |   |   Different classes extending Error.
 |   |-- schema
@@ -17,6 +40,9 @@ Handles core functionality of elek.io Projects like file IO and version control
 |   |   Contains CRUD logic that does file-io as well as utility functions.
 |   |   The methods are mostly used as endpoints
 |   |   so their input is validated against our zod schemas.
+|   |   |-- migrations
+|   |   |   Version-aware schema migrations for Projects, Assets,
+|   |   |   Collections and Entries.
 |   |-- test
 |   |   Additional files and utility functions only used for testing.
 |   |-- util
@@ -28,9 +54,13 @@ Handles core functionality of elek.io Projects like file IO and version control
 |   |-- index.node.ts
 |   |   Exports the ElekIoCore main class which makes the services and API
 |   |   endpoints accessible as well as schemas and utility functions.
+|   |-- index.astro.ts
+|   |   Exports the Astro content loaders for Assets and Entries.
+|   |-- index.cli.ts
+|   |   Entry point for the CLI binary.
 ```
 
-## The concept behind Projects, Collections, Entries, Values and Assets
+## The concept behind Projects, Collections, Entries, Values, Assets and Releases
 
 ```
 |-- Project - e.g. "Website"
@@ -40,6 +70,7 @@ Handles core functionality of elek.io Projects like file IO and version control
 |   |   |   |-- Value - e.g for a post's title: "Quarterly results 7% higher than expected"
 |   |   |   |-- Asset - a reference to a previously added Asset like image, PDF or ZIP
 |   |   |   |-- Entry - a reference to another Entry e.g. to show the user related posts
+|   |-- Release - e.g. "v1.0.0" - a tagged snapshot of the Project at a specific point in time
 ```
 
 ### Projects
@@ -57,7 +88,7 @@ e.g. for a Blog, it could have the following Field definition for each post / En
 - an author that wrote the post (Entry reference)
 
 Each definition like the title, contains additional information for the input Field, that is used to modify it's Value.
-e.g. the title would be a simple one line input Field, that has a maximum lenght of 150 characters and is required for each post. But the content is a markdown editor to easily add formatting. The image let's the user select a jpeg or png from disk. And the author is a reference to another Collection's Entry, so the user is able to choose one of them.
+e.g. the title would be a simple one line input Field, that has a maximum length of 150 characters and is required for each post. But the content is a markdown editor to easily add formatting. The image let's the user select a jpeg or png from disk. And the author is a reference to another Collection's Entry, so the user is able to choose one of them.
 
 ### Entries
 
@@ -65,9 +96,39 @@ Contains Values and references that follow the Collection's Field definitions. W
 
 ### Values
 
-Represent either a single piece of data like the string "How to be successfull in 3 easy steps", a number or a boolean - or a reference to Assets or other Entries.
+Represent either a single piece of data like the string "How to be successful in 3 easy steps", a number or a boolean - or a reference to Assets or other Entries.
 
 ### Assets
 
 Are files / blobs like images (png, jpeg etc.), documents (excel sheets etc.), music or a compressed folder.
 Assets have two files inside the Project's repository - the actual file and additionally a file containing meta information like the size.
+
+### Releases
+
+Are tagged snapshots of a Project at a specific point in time, managed through git tags. They allow you to mark stable versions of your content that can be deployed or exported.
+
+## CLI
+
+The package includes a CLI accessible via the `elek` command:
+
+- `elek generate:client` — Generate a JavaScript/TypeScript API client (ESM or CJS)
+- `elek api:start` — Start a local REST API server (default port 31310)
+- `elek export` — Export Projects to JSON (nested or as separate files)
+
+## Documentation
+
+The `docs/` folder contains additional in-depth documentation on specific topics like the migration and history reading flow.
+
+## Development
+
+```bash
+pnpm install       # Install dependencies
+pnpm dev           # Run tests in watch mode
+pnpm test          # Run tests once
+pnpm coverage      # Run tests with coverage
+pnpm build         # Build all entry points
+pnpm lint          # Lint
+pnpm check-types   # Type check
+pnpm check-format  # Check formatting
+pnpm format        # Format code
+```

package/dist/astro/index.astro.d.mts

@@ -7,7 +7,8 @@ interface ElekAssetsProps {
 }
 interface ElekEntriesOptions {
   projectId: string;
-  collectionId: string;
+  /** Collection UUID or slug */
+  collectionIdOrSlug: string;
 }
 /**
  * Astro content loader for elek.io Assets.