tsprose 0.0.1 → 1.0.0

package/README.md

@@ -14,6 +14,9 @@ Write and structure prose content using TypeScript TSX with strong typing.
 
 TSProse is a **parser + structurer**: you write content in TSX, TSProse turns it into a typed element tree. Rendering, styling, and analysis are up to you.
 
+Think of TSProse as a TeX but written in TypeScript.
+It is a foundation for writing prose. What tags you define and what you do with the prose (render to site or pdf, analyze, serialize, etc) is up to you.
+
 ## Installation
 
 ```bash

package/dist/document.d.ts

@@ -25,4 +25,5 @@ export declare function defineDocument<UniquesTemplate extends DocumentUniquesTe
 export declare function defineDocument<UniquesTemplate extends DocumentUniquesTemplate>(documentId: string, documentParameters: {
     uniques: UniquesTemplate;
 }): DocumentFinalizer<UniquesTemplate>;
+export declare function isDocument(document: any): document is Document;
 export declare function injectDocumentId(documentId: string, injectTo: string, defineDocumentAlias?: string): string;

package/dist/document.js

@@ -42,6 +42,12 @@ export function defineDocument(arg1, arg2) {
     return finalizeDocument;
 }
 //
+// isDocument
+//
+export function isDocument(document) {
+    return Boolean(document?.[DOCUMENT_PREFIX] === true);
+}
+//
 // injectDocumentId
 //
 export function injectDocumentId(documentId, injectTo, defineDocumentAlias) {

package/dist/element.d.ts

@@ -11,21 +11,25 @@ export type ToRawElement<TSchema extends Schema, TagName extends string = string
     storageKey: TSchema['Storage'] extends undefined ? undefined : string;
     children: ToRawElementChildren<TSchema['Children']>;
 } : never;
-type ToRawElementChildren<TChildren> = TChildren extends (infer E extends Schema)[] ? ToRawElement<E>[] : TChildren extends undefined ? undefined : never;
+type ToRawElementChildren<TChildren> = TChildren extends undefined ? undefined : TChildren extends readonly Schema[] ? {
+    [K in keyof TChildren]: TChildren[K] extends Schema ? ToRawElement<TChildren[K]> : TChildren[K];
+} : never;
 export type RawElement = ToRawElement<Schema>;
 export type BlockRawElement = ToRawElement<BlockSchema>;
 export type InlinerRawElement = ToRawElement<InlinerSchema>;
 export type LinkableRawElement = ToRawElement<LinkableSchema>;
 export declare const PROSE_ELEMENT_PREFIX = "__TSPROSE_proseElement";
-export type ToProseElement<TSchema extends Schema> = {
+export type ToProseElement<TSchema extends Schema> = TSchema extends Schema ? {
     [PROSE_ELEMENT_PREFIX]: true;
     schema: TSchema;
-    id: TSchema['linkable'] extends false ? undefined : string;
+    id: false extends TSchema['linkable'] ? TSchema['linkable'] extends false ? undefined : string | undefined : string;
     data: TSchema['Data'];
-    storageKey: TSchema['Storage'] extends undefined ? undefined : string;
+    storageKey: false extends TSchema['Storage'] ? TSchema['linkable'] extends false ? undefined : undefined | string : string;
     children: ToProseElementChildren<TSchema['Children']>;
-};
-type ToProseElementChildren<TChildren> = TChildren extends (infer E extends Schema)[] ? ToProseElement<E>[] : TChildren extends undefined ? undefined : never;
+} : never;
+type ToProseElementChildren<TChildren> = TChildren extends undefined ? undefined : TChildren extends readonly Schema[] ? {
+    [K in keyof TChildren]: TChildren[K] extends Schema ? ToProseElement<TChildren[K]> : TChildren[K];
+} : never;
 export type ProseElement = ToProseElement<Schema>;
 export type BlockProseElement = ToProseElement<BlockSchema>;
 export type InlinerProseElement = ToProseElement<InlinerSchema>;

package/dist/elementUtils.js

@@ -8,6 +8,9 @@ export function makeRawElement(parameters) {
         tagName: parameters.tagName,
     };
     parameters.elementHandler?.(element);
+    if (Array.isArray(element.children) && element.children.length === 0) {
+        delete element.children;
+    }
     element.hash = hash(element.schema.name +
         JSON.stringify(element.data) +
         JSON.stringify(element.children?.map((child) => child.hash).join()), 12);
@@ -19,6 +22,9 @@ export function makeProseElement(parameters) {
         schema: parameters.schema,
     };
     parameters.elementHandler?.(element);
+    if (Array.isArray(element.children) && element.children.length === 0) {
+        delete element.children;
+    }
     return element;
 }
 export function isRawElement(element, schema) {

package/dist/externals.d.ts

@@ -1,57 +1,57 @@
-//
-// Images
-//
-
-declare module '*.png' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.jpg' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.jpeg' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.gif' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.bmp' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.webp' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.svg' {
-  const src: string;
-  export default src;
-}
-
-//
-// Videos
-//
-
-declare module '*.mp4' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.webm' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.ogg' {
-  const src: string;
-  export default src;
-}
+//
+// Images
+//
+
+declare module '*.png' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.jpg' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.jpeg' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.gif' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.bmp' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.webp' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.svg' {
+  const src: string;
+  export default src;
+}
+
+//
+// Videos
+//
+
+declare module '*.mp4' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.webm' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.ogg' {
+  const src: string;
+  export default src;
+}

package/dist/id.d.ts

@@ -1,3 +1,8 @@
-import type { RawElement } from './element.js';
-export type IdMaker = (rawElement: RawElement, takenIds?: Set<string>) => string;
+import type { ProseElement, RawElement } from './element.js';
+export type TakenIds = Map<string, ProseElement>;
+export type IdMaker = (args: {
+    rawElement: RawElement;
+    takenIds?: TakenIds;
+    slugify?: (str: string) => string;
+}) => string;
 export declare const defaultIdMaker: IdMaker;

package/dist/id.js

@@ -1,17 +1,37 @@
-export const defaultIdMaker = (rawElement, takenIds) => {
-    takenIds ||= new Set();
+export const defaultIdMaker = ({ rawElement, takenIds, slugify }) => {
     let id = '';
     const humanReadable = rawElement.uniqueName || rawElement.slug;
     if (humanReadable) {
-        id = humanReadable;
+        id = slugify ? slugify(humanReadable) : humanReadable;
     }
     else {
         id = rawElement.schema.name + '-' + rawElement.hash.substring(0, 9);
     }
-    let candidate = id;
-    let counter = 1;
-    while (takenIds.has(candidate)) {
-        candidate = `${id}-${counter++}`;
+    if (takenIds) {
+        if (rawElement.uniqueName) {
+            // Unique elements keep their id; colliding elements get deduplicated ids
+            if (takenIds.has(id)) {
+                const collidingProse = takenIds.get(id);
+                takenIds.delete(id);
+                const newIdForColliding = collidingProse.schema.name + '-' + collidingProse.id;
+                let candidate = newIdForColliding;
+                let counter = 1;
+                while (takenIds.has(candidate)) {
+                    candidate = `${newIdForColliding}-${counter++}`;
+                }
+                collidingProse.id = candidate;
+                takenIds.set(candidate, collidingProse);
+            }
+        }
+        else {
+            // Non-unique elements find the next available id
+            let candidate = id;
+            let counter = 1;
+            while (takenIds.has(candidate)) {
+                candidate = `${id}-${counter++}`;
+            }
+            id = candidate;
+        }
     }
-    return candidate;
+    return id;
 };

package/dist/index.d.ts

@@ -7,7 +7,6 @@ export * from './element.js';
 export * from './elementUtils.js';
 export * from './error.js';
 export * from './id.js';
-export * from './json.js';
 export * from './rawToProse.js';
 export * from './schema.js';
 export * from './storage.js';

package/dist/index.js

@@ -7,7 +7,6 @@ export * from './element.js';
 export * from './elementUtils.js';
 export * from './error.js';
 export * from './id.js';
-export * from './json.js';
 export * from './rawToProse.js';
 export * from './schema.js';
 export * from './storage.js';

package/dist/rawToProse.d.ts

@@ -1,19 +1,20 @@
 import type { LinkableProseElement, ProseElement, RawElement } from './element.js';
-import { type IdMaker } from './id.js';
+import { type IdMaker, type TakenIds } from './id.js';
 export type RawToProseStep = (elements: {
     rawElement: RawElement;
     proseElement: ProseElement;
 }) => void | Promise<void>;
 export interface RawToProseResult {
     prose: ProseElement;
-    takenIds: Set<string>;
+    takenIds: TakenIds;
     uniques: Record<string, LinkableProseElement>;
 }
 export declare function rawToProse(args: {
     rawProse: RawElement;
-    takenIds?: Set<string>;
+    takenIds?: TakenIds;
     pre?: (rawElement: RawElement) => void | Promise<void>;
     post?: (proseElement: ProseElement) => void | Promise<void>;
     step?: RawToProseStep;
     idMaker?: IdMaker;
+    slugify?: (str: string) => string;
 }): Promise<RawToProseResult>;

package/dist/rawToProse.js

@@ -3,9 +3,9 @@ import { TSProseError } from './error.js';
 import { defaultIdMaker } from './id.js';
 import { isWalkStop, walkPost } from './walk.js';
 export async function rawToProse(args) {
-    const { rawProse, pre, post, step } = args;
+    const { rawProse, pre, post, step, slugify } = args;
     const idMaker = args.idMaker || defaultIdMaker;
-    const takenIds = new Set(args.takenIds);
+    const takenIds = new Map(args.takenIds);
     const uniques = {};
     const prose = await walkPost(rawProse, async (rawElement, children) => {
         if (pre) {
@@ -20,19 +20,22 @@ export async function rawToProse(args) {
         if (rawElement.storageKey) {
             proseElement.storageKey = rawElement.storageKey;
         }
-        if (children) {
+        if (children && children.length > 0) {
             proseElement.children = children;
         }
         if (rawElement.schema.linkable) {
-            const elementId = idMaker(rawElement, takenIds);
+            const elementId = idMaker({ rawElement, takenIds, slugify });
+            if (!elementId.trim()) {
+                throw new TSProseError(`Empty ID generated from "${rawElement.schema.name}" element!\nThis might happen because of wrongly configured "idMaker" or obscure element data that was passed to create an ID!`);
+            }
             if (takenIds.has(elementId)) {
                 throw new TSProseError(`Element ID collision: "${elementId}" is already taken!\nMake sure "idMaker" you are using generates non-repeating IDs!`);
             }
             proseElement.id = elementId;
-            takenIds.add(elementId);
+            takenIds.set(elementId, proseElement);
             if (rawElement.uniqueName) {
                 if (uniques[rawElement.uniqueName]) {
-                    throw new TSProseError(`Duplicate uniqueName: "${rawElement.uniqueName}" is already used by another element!\nIf you are using document prose, make sure not to directly insert imported or manually created external uniques as they might intersect with document uniques!`);
+                    throw new TSProseError(`Duplicate uniqueName: "${rawElement.uniqueName}" is already used by another element!\nIf you are using document prose, make sure not to directly insert imported or manually created external uniques as their names might intersect with document-level uniques names!`);
                 }
                 uniques[rawElement.uniqueName] = proseElement;
             }

package/dist/storage.d.ts

@@ -5,10 +5,13 @@ export interface ProseWithStorage {
     prose: ProseElement;
     storage: ProseStorage;
 }
-export type ElementStorageCreator<TSchema extends Schema> = TSchema['Storage'] extends undefined ? never : (element: ToProseElement<TSchema>) => null | TSchema['Storage'] | Promise<null | TSchema['Storage']>;
+interface _StorageCreatorMethod<TSchema extends Schema> {
+    creator(element: ToProseElement<TSchema>): null | TSchema['Storage'] | Promise<null | TSchema['Storage']>;
+}
+export type ElementStorageCreator<TSchema extends Schema> = TSchema['Storage'] extends undefined ? never : _StorageCreatorMethod<TSchema>['creator'];
 export declare function fillProseStorage(args: {
     prose: ProseElement;
-    storageCreators: Record<string, ElementStorageCreator<any>>;
+    storageCreators: Record<string, ElementStorageCreator<Schema>>;
     alterValue?: (args: {
         element: ToProseElement<Schema>;
         storageKey: string;
@@ -16,3 +19,4 @@ export declare function fillProseStorage(args: {
     }) => any | Promise<any>;
     storage?: ProseStorage;
 }): Promise<ProseStorage>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsprose",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "📜 Write and parse any prose in TypeScript TSX!",
   "license": "MIT",

package/dist/json.d.ts

@@ -1,2 +0,0 @@
-export declare function toJSON(value: unknown, indent?: number): string;
-export declare function fromJSON(json: string): any;

package/dist/json.js

@@ -1,46 +0,0 @@
-import { PROSE_ELEMENT_PREFIX, RAW_ELEMENT_PREFIX } from './element.js';
-import { SCHEMA_PREFIX } from './schema.js';
-function encodeSchema(schema) {
-    return (schema.name +
-        (schema.type === 'block' ? '0' : '1') +
-        (schema.linkable === false ? '0' : schema.linkable === 'always' ? '2' : '1'));
-}
-function decodeSchema(encoded) {
-    const name = encoded.slice(0, -2);
-    const typeFlag = encoded.at(-2);
-    const linkFlag = encoded.at(-1);
-    return {
-        [SCHEMA_PREFIX]: true,
-        name,
-        type: typeFlag === '0' ? 'block' : 'inliner',
-        linkable: linkFlag === '0' ? false : linkFlag === '2' ? 'always' : true,
-    };
-}
-function isElement(obj) {
-    return obj[RAW_ELEMENT_PREFIX] === true || obj[PROSE_ELEMENT_PREFIX] === true;
-}
-export function toJSON(value, indent) {
-    return JSON.stringify(value, function (key, val) {
-        if (!isElement(this))
-            return val;
-        if (key === RAW_ELEMENT_PREFIX || key === PROSE_ELEMENT_PREFIX) {
-            const schema = this.schema;
-            return encodeSchema(schema);
-        }
-        if (key === 'schema') {
-            return undefined;
-        }
-        return val;
-    }, indent);
-}
-export function fromJSON(json) {
-    return JSON.parse(json, function (key, val) {
-        if ((key === RAW_ELEMENT_PREFIX || key === PROSE_ELEMENT_PREFIX) &&
-            typeof val === 'string') {
-            const schema = decodeSchema(val);
-            this.schema = schema;
-            return true;
-        }
-        return val;
-    });
-}