@atom-forge/expose 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-07
+
+### Added
+- Initial package setup: TypeScript sources built with tsup, Bun tests, CI, and releases with `@atom-forge/ship`.
+- AtomForge agent instructions (`AGENTS.md`, `AGENTS/`), the documentation skeleton (book, `docs/en`, `docs/hu`, `README-AI.md`), `TODO.md`, and `notes/`.
+- The allow-list API: `expose`, `compose`, `fieldsOf` for naming plain fields, and the `View`, `Part`, `Stacked` and `Merge` types. A view that returns anything but a plain object is a compile error. An application gathers its views into a plain `views` object.
+- Releases: a tag-triggered publish workflow with npm Trusted Publishing, and public `publishConfig`.
+- The documentation of the API: book chapters, English and Hungarian docs, `README.md`, `README-AI.md`, and AI Notes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gergely Laborci
+
+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.

package/README-AI.md

@@ -0,0 +1,85 @@
+# AI README: @atom-forge/expose
+
+A typed allow-list layer between server data and the client: nothing goes out unless a *view* names it. Use it when a server returns database rows to a client. It has no dependencies and works with any database layer or transport.
+
+The [documentation](./docs/en/index.md) is authoritative where the two disagree; see [README.md](./README.md) for installation.
+
+## Rules
+
+- Copy plain fields with `fieldsOf`; write a view by hand for computed fields and nested data.
+- A view names every field it returns. Never spread `source`, and never return a nested row as it is: run it through its own view.
+- A view says *what* goes out, not *who* may get it. Do the permission check before the call.
+- A view is synchronous and returns a plain object; anything else is a compile error.
+- A later view overwrites earlier keys. To add to a key instead, read it from `output`, build a new value, and mark it `Stacked`.
+- `output` is frozen only at the top level: do not write into its nested values.
+- The allowed list of `fieldsOf<S>()` exists only in the types: never pass it names from a request, and leave objects off `S`.
+
+## API
+
+```ts
+type View<S, O, R extends Part> = (source: S, output: Readonly<O>) => R;
+type Part;          // a plain object: promises, arrays, strings, dates, maps and functions are compile errors
+type Stacked<T>;    // marks a key that adds up; types only, the view does the adding
+type Merge<A, B>;   // keys of B overwrite keys of A; Stacked keys become A[K] & B[K]
+
+// 1–4 views. null and undefined become null without running a view;
+// the result type includes null only if the type of source allows it.
+function expose(source, a, b?, c?, d?): Output | null;
+
+// 2–3 views. The result is a view; its source type requires the fields of all its views.
+// For more views than the limit, compose a composed view.
+function compose(a, b, c?): View;
+
+// Any number of names of S. The row needs only the named fields.
+function fieldsOf<S>(): <K extends keyof S>(...names: K[]) => (source: Pick<S, K>) => Pick<S, K>;
+```
+
+## Minimal example
+
+```ts
+import { compose, expose } from '@atom-forge/expose';
+
+const identity = (source: { id: string; name: string }) => ({
+	id: source.id,
+	name: source.name,
+});
+const contact = (source: { email: string }) => ({ email: source.email });
+const card = compose(identity, contact);
+
+const row = { id: 'u1', name: 'Ada', email: 'ada@example.com', passwordHash: 'secret' };
+
+const output = expose(row, card);
+// { id: 'u1', name: 'Ada', email: 'ada@example.com' }; passwordHash is not on the type either
+```
+
+## Common extensions
+
+Name plain fields with `fieldsOf`, and gather an application's views into a plain `views` object, with the views per entity in their own files:
+
+```ts
+export const fields = fieldsOf<{ id: string; name: string; email: string }>(); // server/views/user.ts
+export const views = { user }; // import * as user from './user'
+return rows.map(row => expose(row, views.user.fields('id', 'name')));
+```
+
+A view that adds to a key:
+
+```ts
+const links = <N extends string>(...names: N[]) =>
+	(source: { links: Record<string, string> }, output: Readonly<Record<string, any>>) => {
+		const picked = {} as Partial<Record<N, string>>;
+		for (const name of names) if (Object.prototype.hasOwnProperty.call(source.links, name)) picked[name] = source.links[name];
+		return { links: { ...output.links, ...picked } as Stacked<Partial<Record<N, string>>> };
+	};
+```
+
+Type its `output` as `Readonly<Record<string, any>>`, so it fits after any earlier view.
+
+## Pitfalls
+
+- The library cannot stop code from returning a row without calling it; a project that needs this adds its own guard test.
+- Without the `Stacked` mark, the types say the key was replaced, even though the view added to it.
+
+## Documentation map
+
+[`docs/en/index.md`](./docs/en/index.md) covers getting started, views, organizing an application, the API reference, the pitfalls, and upgrading. The Hungarian translation is [`docs/hu/index.md`](./docs/hu/index.md).

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @atom-forge/expose
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed allow-list layer between server data and the client: nothing goes out unless a *view* names it, so a new column stays on the server by default.
+
+For coding assistants, see [README-AI.md](./README-AI.md).
+
+## Installation
+
+```bash
+bun add @atom-forge/expose
+```
+
+## Example
+
+```ts
+import { compose, expose } from '@atom-forge/expose';
+
+const identity = (source: { id: string; name: string }) => ({ id: source.id, name: source.name });
+const contact = (source: { email: string }) => ({ email: source.email });
+const card = compose(identity, contact);
+
+const row = { id: 'u1', name: 'Ada', email: 'ada@example.com', passwordHash: 'secret' };
+
+expose(row, card);
+// { id: 'u1', name: 'Ada', email: 'ada@example.com' }
+```
+
+## Documentation
+
+- [The Expose book](https://books.atom-forge.eu) — the full documentation as a multi-page book.
+- [English documentation](docs/en/index.md) ([magyarul](docs/hu/index.md)) — the same documentation shipped with the package, including the upgrade notes.
+- [AI guide](README-AI.md) — the entry point for coding agents using the package.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Allow-list layer between server data and the client: nothing leaves unless a view names it.
+ *
+ * A view receives the source row and what the earlier views built, and returns only its own part. Later parts
+ * overwrite earlier keys; a view that wants to add to a key reads it from `output` and marks it `Stacked`.
+ * Never spread `source` in a view: that would let every column out.
+ */
+type View<S, O, R extends Part> = (source: S, output: Readonly<O>) => R;
+/**
+ * What a view may return: a plain object. The run-time merge is an object spread, so a promise would lose its data and
+ * an array or a string would become numbered keys. Only symbol keys are excluded, so no field name can collide.
+ */
+type Part = object & {
+    readonly [Symbol.iterator]?: never;
+    readonly [Symbol.toStringTag]?: never;
+    readonly [Symbol.hasInstance]?: never;
+    readonly [Symbol.toPrimitive]?: never;
+};
+declare const stacked: unique symbol;
+/** Marks a key that adds to the earlier value instead of replacing it; the view does the adding with `output`. */
+type Stacked<T> = T & {
+    readonly [stacked]?: true;
+};
+/** The keys of `B` overwrite the keys of `A`, as the merge at run time does; `Stacked` keys add up. */
+type Merge<A, B> = {
+    [K in keyof A | keyof B]: K extends keyof B ? K extends keyof A ? (typeof stacked extends keyof B[K] ? A[K] & B[K] : B[K]) : B[K] : K extends keyof A ? A[K] : never;
+};
+type Nullish<S> = null extends S ? null : undefined extends S ? null : never;
+/** Builds the output of a row (null and undefined become null, so an optional relation needs no check at the call). */
+declare function expose<S, A extends Part>(source: S, a: View<NonNullable<S>, {}, A>): A | Nullish<S>;
+declare function expose<S, A extends Part, B extends Part>(source: S, a: View<NonNullable<S>, {}, A>, b: View<NonNullable<S>, A, B>): Merge<A, B> | Nullish<S>;
+declare function expose<S, A extends Part, B extends Part, C extends Part>(source: S, a: View<NonNullable<S>, {}, A>, b: View<NonNullable<S>, A, B>, c: View<NonNullable<S>, Merge<A, B>, C>): Merge<Merge<A, B>, C> | Nullish<S>;
+declare function expose<S, A extends Part, B extends Part, C extends Part, D extends Part>(source: S, a: View<NonNullable<S>, {}, A>, b: View<NonNullable<S>, A, B>, c: View<NonNullable<S>, Merge<A, B>, C>, d: View<NonNullable<S>, Merge<Merge<A, B>, C>, D>): Merge<Merge<Merge<A, B>, C>, D> | Nullish<S>;
+/** Names a combination of views; the result is a view itself. */
+declare function compose<S1, A extends Part, S2, B extends Part>(a: View<S1, {}, A>, b: View<S2, A, B>): View<S1 & S2, {}, Merge<A, B>>;
+declare function compose<S1, A extends Part, S2, B extends Part, S3, C extends Part>(a: View<S1, {}, A>, b: View<S2, A, B>, c: View<S3, Merge<A, B>, C>): View<S1 & S2 & S3, {}, Merge<Merge<A, B>, C>>;
+/**
+ * Makes a view factory for an entity: `S` lists the fields that may go out by name, the factory takes the names.
+ * The list exists only in the types: never pass it names from a request, and leave objects off `S`.
+ */
+declare function fieldsOf<S>(): <K extends keyof S>(...names: K[]) => (source: Pick<S, K>) => Pick<S, K>;
+
+export { type Merge, type Part, type Stacked, type View, compose, expose, fieldsOf };

package/dist/index.js

@@ -0,0 +1,24 @@
+// src/index.ts
+function run(source, views, start) {
+  let output = start;
+  for (const view of views) output = { ...output, ...view(source, Object.freeze(output)) };
+  return output;
+}
+function expose(source, ...views) {
+  return source === null || source === void 0 ? null : run(source, views, {});
+}
+function compose(...views) {
+  return (source, output) => run(source, views, output);
+}
+function fieldsOf() {
+  return (...names) => (source) => {
+    const picked = {};
+    for (const name of names) picked[name] = source[name];
+    return picked;
+  };
+}
+export {
+  compose,
+  expose,
+  fieldsOf
+};

package/docs/en/index.md

@@ -0,0 +1,266 @@
+<!-- Derived from the book in book/ (https://books.atom-forge.eu). Change the book first, then update this file and docs/hu/index.md. -->
+
+# Expose
+
+`@atom-forge/expose` is a small TypeScript library that decides what leaves the server: nothing goes to the client unless a *view* names it. When a table gets a new column, that column stays on the server until someone adds it to a view, and the compiler knows the exact shape of what went out.
+
+It has no dependencies and works with any database layer or transport, because a view is a plain function.
+
+## Getting started
+
+### Installation
+
+```sh
+bun add @atom-forge/expose
+```
+
+The package is ESM-only and ships its own type declarations.
+
+### Write a view and build an output
+
+A view receives the source row and returns the part it is responsible for, naming every field. `expose` runs the views on a row and merges what they return:
+
+```ts
+import { expose } from '@atom-forge/expose';
+
+const identity = (source: { id: string; name: string }) => ({
+	id: source.id,
+	name: source.name,
+});
+const contact = (source: { email: string }) => ({ email: source.email });
+
+const row = { id: 'u1', name: 'Ada', email: 'ada@example.com', passwordHash: 'secret' };
+
+const output = expose(row, identity, contact);
+// { id: 'u1', name: 'Ada', email: 'ada@example.com' }
+
+output.email; // string
+// output.passwordHash; // compile error: it is not on the output
+```
+
+`passwordHash` stays on the server because no view names it. The same holds for any column added to the table later.
+
+### Naming plain fields
+
+For fields copied as they are, `fieldsOf` saves writing the view by hand. Give it a type that lists what may go out by name, then name the fields at the call:
+
+```ts
+import { expose, fieldsOf } from '@atom-forge/expose';
+
+type PublicUser = { id: string; name: string; email: string };
+const fields = fieldsOf<PublicUser>();
+
+const output = expose(row, fields('id', 'name'));
+// { id: 'u1', name: 'Ada' }
+```
+
+### Rows that may be missing
+
+`null` and `undefined` become `null` without running a view, so an optional relation needs no check at the call. The result type includes `null` only when the source type can be missing:
+
+```ts
+const author = row as typeof row | null;
+const output = expose(author, identity); // { id: string; name: string } | null
+```
+
+## Views
+
+A view has the shape `(source, output) => ownPart`. `source` is the row, and `output` is what the earlier views have built. The view returns only its own part; `expose` does the merging.
+
+### Naming fields with `fieldsOf`
+
+`fieldsOf<S>()` makes a view factory for an entity. `S` lists the fields that may go out by name; the factory takes the names and returns a view. Use it for fields copied as they are, and write a view by hand for computed fields and nested data.
+
+```ts
+import { expose, fieldsOf } from '@atom-forge/expose';
+
+type PublicUser = { id: string; name: string; email: string };
+const fields = fieldsOf<PublicUser>();
+
+const output = expose(row, fields('id', 'name'));
+// { id: 'u1', name: 'Ada' }
+
+output.email; // compile error: it was not named
+fields('nmae'); // compile error: no such field
+fields('passwordHash'); // compile error: it is not on PublicUser
+```
+
+The row needs only the named fields, so a query that read just some of the columns fits, and naming a column it did not read is a compile error:
+
+```ts
+const partial = { id: 'u1', name: 'Ada' };
+
+expose(partial, fields('id', 'name'));
+expose(partial, fields('email')); // compile error: the row has no email
+```
+
+The number of names is not limited. The result is a view like any other, so it can be composed and combined with other views:
+
+```ts
+expose(row, fields('id', 'name'), contact);
+```
+
+The empty call in `fieldsOf<PublicUser>()` is needed because TypeScript cannot take one type argument by hand and infer another.
+
+### Later views overwrite
+
+The parts merge from left to right, so a later key replaces an earlier one, in the types as well:
+
+```ts
+const output = expose(row, identity, () => ({ name: 'Anonymous' }));
+// { id: 'u1', name: 'Anonymous' }
+```
+
+### Reading the earlier output
+
+A view can build on what is already there. `output` is frozen, so a view cannot change it in place:
+
+```ts
+const label = (_source: unknown, output: Readonly<{ name: string; email: string }>) => ({
+	label: `${output.name} <${output.email}>`,
+});
+
+expose(row, identity, contact, label);
+```
+
+### Composing views
+
+`compose` names a combination of views. The result is a view, so it can be passed to `expose` or composed further. Its source type requires the fields of all of its views:
+
+```ts
+import { compose } from '@atom-forge/expose';
+
+const card = compose(identity, contact);
+const output = expose(row, card);
+```
+
+A composed view keeps what earlier views built, like any other view.
+
+### Adding to a key with `Stacked`
+
+Sometimes several views contribute to one key, for example when each one picks a few named links. Such a view reads the key from `output`, returns the combined value, and marks it with `Stacked`. The mark tells the types that the key adds up instead of being replaced; the view itself does the adding at run time.
+
+```ts
+import { expose, type Stacked } from '@atom-forge/expose';
+
+const links = <N extends string>(...names: N[]) =>
+	(source: { links: Record<string, string> }, output: Readonly<Record<string, any>>) => {
+		const picked = {} as Partial<Record<N, string>>;
+		for (const name of names) if (Object.prototype.hasOwnProperty.call(source.links, name)) picked[name] = source.links[name];
+		return { links: { ...output.links, ...picked } as Stacked<Partial<Record<N, string>>> };
+	};
+
+const row = { links: { home: 'h', work: 'w', private: 'p' } as Record<string, string> };
+
+const output = expose(row, links('home'), links('work'));
+// { links: { home: 'h', work: 'w' } }
+// output.links.private; // compile error: it was not named
+```
+
+Declare `output` as `Readonly<Record<string, any>>` in such a view, so that it fits after any earlier view.
+
+## Organizing an application
+
+The library knows nothing about your entities. A practical layout keeps the views of each entity in one file and gathers them into a plain `views` object, so every call site reads the same way.
+
+```ts
+// server/views/user.ts
+import { fieldsOf } from '@atom-forge/expose';
+
+type PublicUser = { id: string; name: string; email: string };
+
+export const fields = fieldsOf<PublicUser>();
+export const privateSalary = (source: { salary: number }) => ({ salary: source.salary });
+```
+
+```ts
+// server/views/index.ts
+import * as user from './user';
+
+export const views = { user };
+```
+
+```ts
+// at a call site
+import { expose } from '@atom-forge/expose';
+import { views } from '../views';
+
+return rows.map(row => expose(row, views.user.fields('id', 'name')));
+```
+
+### Who, and what
+
+Keep two questions apart. The module decides *who* may get the data, with its usual permission check. A view only says *what* goes out, and it cannot check anything about the caller. When a view carries sensitive data, make that visible in its name and call it only after the check:
+
+```ts
+assertCanReadSalary(viewer, row); // your own permission check
+return expose(row, views.user.fields('id', 'name'), views.user.privateSalary);
+```
+
+### Keeping raw rows out
+
+The library cannot stop code from returning a row without calling `expose`. If that matters in your project, add a test that scans the server code for the outputs you want to forbid, with an explicit allow-list for the exceptions.
+
+## API reference
+
+### `expose(source, ...views)`
+
+```ts
+function expose<S, A>(source: S, a: View<NonNullable<S>, {}, A>): A | Nullish<S>;
+```
+
+Runs the views on `source` from left to right and returns the merged output. It takes one to four views; the signature above shows one. For more, combine some with `compose`.
+
+If `source` is `null` or `undefined`, it returns `null` and runs no view. The result type includes `null` only when the type of `source` allows a missing value.
+
+### `compose(...views)`
+
+```ts
+function compose<S1, A, S2, B>(a: View<S1, {}, A>, b: View<S2, A, B>): View<S1 & S2, {}, Merge<A, B>>;
+```
+
+Returns a new view that runs the given views in order, on top of the output it receives. It takes two or three views; the signature above shows two. For more, compose a composed view.
+
+### `fieldsOf<S>()`
+
+```ts
+function fieldsOf<S>(): <K extends keyof S>(...names: K[]) => (source: Pick<S, K>) => Pick<S, K>;
+```
+
+Returns a factory that takes field names of `S` and returns a view copying those fields. The list of allowed fields exists only in the types: at run time the view copies the names it receives.
+
+### `View<S, O, R>`
+
+```ts
+type View<S, O, R extends Part> = (source: S, output: Readonly<O>) => R;
+```
+
+`S` is the source the view reads, `O` is the output built before it, and `R` is the part it returns. `R` must be a plain object: a promise, an array, a string, a date, a map, a function or a possibly `null` value is a compile error, because it could not be merged.
+
+### `Part`
+
+What a view may return: a plain object. Only symbol keys are excluded, so a field named `then` or `length` is fine.
+
+### `Stacked<T>`
+
+Marks the type of a key that adds to the earlier value instead of replacing it. It affects the types only; the view does the adding with `output`.
+
+### `Merge<A, B>`
+
+The type of merging `B` over `A`: the keys of `B` overwrite the keys of `A`, and `Stacked` keys become `A[K] & B[K]`.
+
+## Pitfalls
+
+The allow-list holds only as far as the views name their fields. These are the things the library cannot check for you.
+
+- **Spreading the source.** `({ ...source })` lets every column out, including those added later. Name each field.
+- **Returning a nested object as it is.** `({ author: source.author })` sends the whole `author` row. Run it through its own view: `author: expose(source.author, identity)`.
+- **Passing names from a request to `fields`.** The list of allowed fields in `fieldsOf<S>()` exists only in the types. `fields(...request.fields)` with a cast copies whatever the caller asks for. Name the fields in the code.
+- **Listing an object in the type of `fieldsOf`.** A field on that type goes out as it is, so an object goes out whole, with every key it gets later. Leave it off and write a view for it.
+- **Treating a view as a permission check.** A view says what goes out, not who may get it. Do the permission check before the call.
+- **Changing a nested value of `output`.** `output` is frozen only at the top level. A view that writes into `output.links` changes an earlier view's value. Build a new object instead, as in the stacking example.
+- **Forgetting the `Stacked` mark.** Without it, the types say the key was replaced even though your view added to it, so the earlier names are missing from the output type.
+
+## Upgrading
+
+0.1.0 is the first published version, so there is nothing to upgrade from yet.

package/docs/hu/index.md

@@ -0,0 +1,266 @@
+<!-- A docs/en/index.md magyar fordítása. Előbb a book és a docs/en változik, utána ez a fájl. -->
+
+# Expose
+
+Az `@atom-forge/expose` egy kis TypeScript-könyvtár, amely azt szabályozza, mi hagyhatja el a szervert: semmi nem jut el a klienshez, amit egy *nézet* (view) meg nem nevez. Ha egy tábla új oszlopot kap, az mindaddig a szerveren marad, amíg valaki hozzá nem adja egy nézethez, és a fordító pontosan ismeri a kimenő adat alakját.
+
+Nincs függősége, és bármilyen adatbázisréteggel vagy átviteli móddal használható, mert a nézet egy egyszerű függvény.
+
+## Első lépések
+
+### Telepítés
+
+```sh
+bun add @atom-forge/expose
+```
+
+A csomag csak ESM-ként érhető el, és tartalmazza a saját típusdeklarációit.
+
+### Nézet írása és a kimenet felépítése
+
+A nézet megkapja a forrássort, és visszaadja azt a részt, amelyért felel, minden mezőt megnevezve. Az `expose` lefuttatja a nézeteket a soron, és összefésüli, amit visszaadnak:
+
+```ts
+import { expose } from '@atom-forge/expose';
+
+const identity = (source: { id: string; name: string }) => ({
+	id: source.id,
+	name: source.name,
+});
+const contact = (source: { email: string }) => ({ email: source.email });
+
+const row = { id: 'u1', name: 'Ada', email: 'ada@example.com', passwordHash: 'secret' };
+
+const output = expose(row, identity, contact);
+// { id: 'u1', name: 'Ada', email: 'ada@example.com' }
+
+output.email; // string
+// output.passwordHash; // fordítási hiba: nincs a kimeneten
+```
+
+A `passwordHash` a szerveren marad, mert egyetlen nézet sem nevezi meg. Ugyanez igaz minden oszlopra, amelyet később adnak a táblához.
+
+### Egyszerű mezők megnevezése
+
+Változatlanul másolt mezőknél a `fieldsOf` megspórolja a nézet kézi megírását. Adj meg neki egy típust, amely felsorolja a név szerint kiadható mezőket, majd a hívásnál nevezd meg őket:
+
+```ts
+import { expose, fieldsOf } from '@atom-forge/expose';
+
+type PublicUser = { id: string; name: string; email: string };
+const fields = fieldsOf<PublicUser>();
+
+const output = expose(row, fields('id', 'name'));
+// { id: 'u1', name: 'Ada' }
+```
+
+### Hiányozható sorok
+
+A `null` és az `undefined` nézet futtatása nélkül `null` lesz, így egy opcionális kapcsolatnál nem kell ellenőrzés a hívás helyén. Az eredmény típusa csak akkor tartalmazza a `null`-t, ha a forrás típusa megengedi a hiányt:
+
+```ts
+const author = row as typeof row | null;
+const output = expose(author, identity); // { id: string; name: string } | null
+```
+
+## Nézetek
+
+A nézet alakja `(source, output) => sajátRész`. A `source` a sor, az `output` pedig az, amit a korábbi nézetek felépítettek. A nézet csak a saját részét adja vissza; az összefésülést az `expose` végzi.
+
+### Mezők megnevezése a `fieldsOf` függvénnyel
+
+A `fieldsOf<S>()` nézetgyárat készít egy entitáshoz. Az `S` felsorolja a név szerint kiadható mezőket; a gyár a neveket kapja meg, és egy nézetet ad vissza. Változatlanul másolt mezőkhöz használd, számolt mezőkhöz és beágyazott adatokhoz pedig írj kézzel nézetet.
+
+```ts
+import { expose, fieldsOf } from '@atom-forge/expose';
+
+type PublicUser = { id: string; name: string; email: string };
+const fields = fieldsOf<PublicUser>();
+
+const output = expose(row, fields('id', 'name'));
+// { id: 'u1', name: 'Ada' }
+
+output.email; // fordítási hiba: nem lett megnevezve
+fields('nmae'); // fordítási hiba: nincs ilyen mező
+fields('passwordHash'); // fordítási hiba: nincs a PublicUser típusban
+```
+
+A sortól csak a megnevezett mezőket kéri, így egy csak néhány oszlopot beolvasó lekérdezés is megfelel, a be nem olvasott oszlop megnevezése pedig fordítási hiba:
+
+```ts
+const partial = { id: 'u1', name: 'Ada' };
+
+expose(partial, fields('id', 'name'));
+expose(partial, fields('email')); // fordítási hiba: a sorban nincs email
+```
+
+A nevek száma nincs korlátozva. Az eredmény ugyanolyan nézet, mint a többi, tehát összeállítható és kombinálható más nézetekkel:
+
+```ts
+expose(row, fields('id', 'name'), contact);
+```
+
+A `fieldsOf<PublicUser>()` üres hívására azért van szükség, mert a TypeScript nem enged egy típusparamétert kézzel megadni, a másikat pedig kikövetkeztetni.
+
+### A későbbi nézetek felülírnak
+
+A részek balról jobbra fésülődnek össze, így a későbbi kulcs lecseréli a korábbit, a típusokban is:
+
+```ts
+const output = expose(row, identity, () => ({ name: 'Anonymous' }));
+// { id: 'u1', name: 'Anonymous' }
+```
+
+### A korábbi kimenet olvasása
+
+Egy nézet építhet arra, ami már megvan. Az `output` fagyasztott, így a nézet nem tudja helyben módosítani:
+
+```ts
+const label = (_source: unknown, output: Readonly<{ name: string; email: string }>) => ({
+	label: `${output.name} <${output.email}>`,
+});
+
+expose(row, identity, contact, label);
+```
+
+### Nézetek összeállítása
+
+A `compose` nevet ad nézetek egy kombinációjának. Az eredmény maga is nézet, tehát átadható az `expose`-nak, vagy tovább kombinálható. A forrástípusa az összes nézete mezőit megköveteli:
+
+```ts
+import { compose } from '@atom-forge/expose';
+
+const card = compose(identity, contact);
+const output = expose(row, card);
+```
+
+Az összeállított nézet megtartja, amit a korábbi nézetek felépítettek, mint bármely más nézet.
+
+### Hozzáadás egy kulcshoz a `Stacked` típussal
+
+Néha több nézet is hozzájárul ugyanahhoz a kulcshoz, például amikor mindegyik néhány megnevezett linket választ ki. Az ilyen nézet kiolvassa a kulcsot az `output`-ból, visszaadja az egyesített értéket, és `Stacked` jelöléssel látja el. A jelölés azt mondja a típusoknak, hogy a kulcs összeadódik, nem cserélődik; futásidőben az összeadást maga a nézet végzi.
+
+```ts
+import { expose, type Stacked } from '@atom-forge/expose';
+
+const links = <N extends string>(...names: N[]) =>
+	(source: { links: Record<string, string> }, output: Readonly<Record<string, any>>) => {
+		const picked = {} as Partial<Record<N, string>>;
+		for (const name of names) if (Object.prototype.hasOwnProperty.call(source.links, name)) picked[name] = source.links[name];
+		return { links: { ...output.links, ...picked } as Stacked<Partial<Record<N, string>>> };
+	};
+
+const row = { links: { home: 'h', work: 'w', private: 'p' } as Record<string, string> };
+
+const output = expose(row, links('home'), links('work'));
+// { links: { home: 'h', work: 'w' } }
+// output.links.private; // fordítási hiba: nem lett megnevezve
+```
+
+Az ilyen nézetben az `output` típusa legyen `Readonly<Record<string, any>>`, hogy bármely korábbi nézet után használható legyen.
+
+## Egy alkalmazás felépítése
+
+A könyvtár semmit nem tud az entitásaidról. Bevált felépítés, ha minden entitás nézetei egy fájlban vannak, és egy közönséges `views` objektumba gyűlnek, így minden hívás ugyanúgy olvasható.
+
+```ts
+// server/views/user.ts
+import { fieldsOf } from '@atom-forge/expose';
+
+type PublicUser = { id: string; name: string; email: string };
+
+export const fields = fieldsOf<PublicUser>();
+export const privateSalary = (source: { salary: number }) => ({ salary: source.salary });
+```
+
+```ts
+// server/views/index.ts
+import * as user from './user';
+
+export const views = { user };
+```
+
+```ts
+// a hívás helyén
+import { expose } from '@atom-forge/expose';
+import { views } from '../views';
+
+return rows.map(row => expose(row, views.user.fields('id', 'name')));
+```
+
+### Ki és mit
+
+Két kérdést tarts külön. A modul dönti el, *ki* kaphatja meg az adatot, a szokásos jogosultság-ellenőrzésével. A nézet csak azt mondja meg, *mi* megy ki, és semmit nem tud ellenőrizni a hívóról. Ha egy nézet érzékeny adatot visz, ez látsszon a nevén, és csak az ellenőrzés után hívd:
+
+```ts
+assertCanReadSalary(viewer, row); // a saját jogosultság-ellenőrzésed
+return expose(row, views.user.fields('id', 'name'), views.user.privateSalary);
+```
+
+### A nyers sorok távol tartása
+
+A könyvtár nem tudja megakadályozni, hogy a kód `expose` hívása nélkül adjon vissza egy sort. Ha ez a projektedben számít, írj egy tesztet, amely megkeresi a szerverkódban a tiltani kívánt kimeneteket, a kivételekhez pedig explicit engedélylistát használ.
+
+## API-referencia
+
+### `expose(source, ...views)`
+
+```ts
+function expose<S, A>(source: S, a: View<NonNullable<S>, {}, A>): A | Nullish<S>;
+```
+
+Balról jobbra lefuttatja a nézeteket a `source` értéken, és visszaadja az összefésült kimenetet. Egy–négy nézetet fogad; a fenti aláírás az egynézetes alakot mutatja. Ennél többhöz kombináld őket a `compose` függvénnyel.
+
+Ha a `source` `null` vagy `undefined`, `null`-t ad vissza, és egyetlen nézetet sem futtat. Az eredmény típusa csak akkor tartalmazza a `null`-t, ha a `source` típusa megengedi a hiányzó értéket.
+
+### `compose(...views)`
+
+```ts
+function compose<S1, A, S2, B>(a: View<S1, {}, A>, b: View<S2, A, B>): View<S1 & S2, {}, Merge<A, B>>;
+```
+
+Új nézetet ad vissza, amely sorban lefuttatja a megadott nézeteket a kapott kimenetre építve. Két vagy három nézetet fogad; a fenti aláírás a kétnézetes alakot mutatja. Ennél többhöz egy már összeállított nézetet kombinálj tovább.
+
+### `fieldsOf<S>()`
+
+```ts
+function fieldsOf<S>(): <K extends keyof S>(...names: K[]) => (source: Pick<S, K>) => Pick<S, K>;
+```
+
+Olyan gyárat ad vissza, amely az `S` mezőneveit kapja meg, és egy ezeket a mezőket másoló nézetet ad vissza. Az engedélyezett mezők listája csak a típusokban létezik: futásidőben a nézet azokat a neveket másolja, amelyeket megkapott.
+
+### `View<S, O, R>`
+
+```ts
+type View<S, O, R extends Part> = (source: S, output: Readonly<O>) => R;
+```
+
+Az `S` a nézet által olvasott forrás, az `O` az előtte felépített kimenet, az `R` pedig a visszaadott rész. Az `R` egyszerű objektum legyen: a promise, a tömb, a szöveg, a dátum, a map, a függvény és az esetleg `null` érték fordítási hiba, mert nem fésülhető össze.
+
+### `Part`
+
+Amit egy nézet visszaadhat: egyszerű objektum. Csak szimbólumkulcsok alapján szűr, így egy `then` vagy `length` nevű mező használható.
+
+### `Stacked<T>`
+
+Olyan kulcs típusát jelöli, amely a korábbi értékhez hozzáad, nem pedig lecseréli. Csak a típusokra hat; az összeadást a nézet végzi az `output` segítségével.
+
+### `Merge<A, B>`
+
+A `B` `A` fölé fésülésének típusa: a `B` kulcsai felülírják az `A` kulcsait, a `Stacked` kulcsok pedig `A[K] & B[K]` típusúak lesznek.
+
+## Buktatók
+
+Az engedélylista csak addig véd, amíg a nézetek megnevezik a mezőiket. Ezeket a könyvtár nem tudja helyetted ellenőrizni.
+
+- **A forrás szétterítése.** A `({ ...source })` minden oszlopot kienged, a később hozzáadottakat is. Nevezz meg minden mezőt.
+- **Beágyazott objektum változatlan visszaadása.** A `({ author: source.author })` a teljes `author` sort kiküldi. Futtasd a saját nézetén keresztül: `author: expose(source.author, identity)`.
+- **Kérésből jövő nevek átadása a `fields` függvénynek.** A `fieldsOf<S>()` engedélyezett mezőinek listája csak a típusokban létezik. A `fields(...request.fields)` egy típuskényszerítéssel azt másolja, amit a hívó kér. A mezőket a kódban nevezd meg.
+- **Objektum felvétele a `fieldsOf` típusába.** Az ebben a típusban szereplő mező változatlanul kimegy, így egy objektum is egészben, minden később kapott kulcsával együtt. Hagyd ki a típusból, és írj hozzá nézetet.
+- **A nézet jogosultság-ellenőrzésként kezelése.** A nézet azt mondja meg, mi megy ki, azt nem, hogy ki kaphatja meg. A jogosultságot a hívás előtt ellenőrizd.
+- **Az `output` beágyazott értékének módosítása.** Az `output` csak a legfelső szinten fagyasztott. Ha egy nézet az `output.links` értékébe ír, egy korábbi nézet értékét változtatja meg. Inkább új objektumot építs, ahogy a `Stacked` példában.
+- **A `Stacked` jelölés elhagyása.** Nélküle a típusok szerint a kulcs lecserélődött, pedig a nézet hozzáadott, így a korábbi nevek hiányoznak a kimenet típusából.
+
+## Frissítés
+
+A 0.1.0 az első kiadott verzió, így még nincs miről frissíteni.

package/package.json

@@ -1,6 +1,63 @@
 {
-  "name": "@atom-forge/expose",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@atom-forge/expose",
+	"version": "0.1.0",
+	"description": "Typed allow-list layer between server data and the client: nothing goes out unless a view names it",
+	"keywords": [
+		"allow-list",
+		"expose",
+		"serialization",
+		"security",
+		"typescript"
+	],
+	"author": {
+		"name": "Gergely Laborci",
+		"url": "https://github.com/laborci"
+	},
+	"license": "MIT",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/atom-forge/expose.git"
+	},
+	"files": [
+		"dist",
+		"docs",
+		"README-AI.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"build": "tsup",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "bun run typecheck && bun test && bun run build",
+		"pub-check": "ship-it check",
+		"pub": "ship-it"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"ship": {
+		"verify": [
+			"bun run typecheck",
+			"bun test",
+			"bun run build",
+			"npm pack --dry-run --ignore-scripts"
+		]
+	},
+	"devDependencies": {
+		"@atom-forge/ship": "file:../ship",
+		"@types/bun": "^1.4.4",
+		"@types/node": "^25.3.1",
+		"tsup": "^8.5.1",
+		"typescript": "^5.0.0"
+	}
+}