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.
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'));
output.email;
fields('nmae');
fields('passwordHash');
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:
const partial = { id: 'u1', name: 'Ada' };
expose(partial, fields('id', 'name'));
expose(partial, fields('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:
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:
const output = expose(row, identity, () => ({ 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:
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:
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.
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'));
Declare output as Readonly<Record<string, any>> in such a view, so that it fits after any earlier view.
Views
A view has the shape
(source, output) => ownPart.sourceis the row, andoutputis what the earlier views have built. The view returns only its own part;exposedoes the merging.Naming fields with
fieldsOffieldsOf<S>()makes a view factory for an entity.Slists 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.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 PublicUserThe 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:
const partial = { id: 'u1', name: 'Ada' }; expose(partial, fields('id', 'name')); expose(partial, fields('email')); // compile error: the row has no emailThe number of names is not limited. The result is a view like any other, so it can be composed and combined with other views:
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:
const output = expose(row, identity, () => ({ name: 'Anonymous' })); // { id: 'u1', name: 'Anonymous' }Reading the earlier output
A view can build on what is already there.
outputis frozen, so a view cannot change it in place:const label = (_source: unknown, output: Readonly<{ name: string; email: string }>) => ({ label: `${output.name} <${output.email}>`, }); expose(row, identity, contact, label);Composing views
composenames a combination of views. The result is a view, so it can be passed toexposeor composed further. Its source type requires the fields of all of its views: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
StackedSometimes 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 withStacked. The mark tells the types that the key adds up instead of being replaced; the view itself does the adding at run time.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 namedDeclare
outputasReadonly<Record<string, any>>in such a view, so that it fits after any earlier view.