takerofnotes/takerofnotes-plugin-sdk
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update testing and versioning

Browse Source
This commit is contained in:
nicwands
2026-03-24 13:56:03 -04:00
parent 40344e4e74
commit 771778fe4a
9 changed files with 178 additions and 1105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.nvmrc Normal file
View File

@@ -0,0 +1 @@
22

10
README.md
View File

@@ -10,7 +10,7 @@ It includes:
- `definePlugin()` helper
- Runtime plugin validation
- Strong TypeScript types
- API version enforcement
- Semver-based API version enforcement
# Installation
@@ -50,7 +50,7 @@ export default definePlugin({
name: 'My Adapter',
description: 'Example storage adapter',
version: '1.0.0',
apiVersion: '1.0.0',
apiVersion: '0.3.1',
configSchema: [],
createAdapter(config) {
return new MyAdapter(config)
@@ -155,13 +155,17 @@ In your plugin's package.json:
"version": "1.0.0",
"type": "module",
"peerDependencies": {
"@nicwands/notes-plugin-sdk": "^0.1.0"
"@nicwands/notes-plugin-sdk": "^0.3.0"
}
}
```
Use peerDependencies to ensure compatibility with the host app.
# API Versioning
The SDK uses semver range matching for API versions. Your plugin's `apiVersion` should fall within the supported range exported as `SUPPORTED_API_RANGE` from the SDK. Minor and patch version changes in the SDK remain compatible with your plugin.
# Security Considerations
Plugins execute in the Notes main process.

998
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

7
package.json
View File

@@ -7,7 +7,7 @@
"types": "dist/index.d.ts",
"repository": {
"type": "git",
"url": "git+https://github.com/nicwands/takerofnotes-plugin-sdk.git"
"url": "git+https://git.alt-tuning.co/takerofnotes/takerofnotes-plugin-sdk"
},
"files": [
"dist"
@@ -27,11 +27,12 @@
"author": "nicwands",
"license": "MIT",
"devDependencies": {
"@types/semver": "^7.7.1",
"tsup": "^8.5.1",
"typescript": "^5.9.3",
"vitest": "^3.2.4"
"typescript": "^5.9.3"
},
"dependencies": {
"semver": "^7.7.4",
"zod": "^4.3.6"
}
}

1
src/BaseNotesAdapter.ts
View File

@@ -10,4 +10,5 @@ export abstract class BaseNotesAdapter {
abstract create(note: any): Promise<void>
abstract update(note: any): Promise<void>
abstract delete(id: string): Promise<void>
abstract testConnection(): Promise<boolean>
}

4
src/index.ts
View File

@@ -1,6 +1,6 @@
export { BaseNotesAdapter } from './BaseNotesAdapter'
export { definePlugin } from './definePlugin'
export { validatePlugin, SUPPORTED_API_VERSION } from './validatePlugin'
export { runPluginTests, createTestNote } from './testPlugin'
export { validatePlugin, SUPPORTED_API_RANGE } from './validatePlugin'
export { describePluginTests, createTestNote } from './testPlugin'
export type { NotesPlugin, ConfigField } from './types'
export type { TestNote, TestPluginOptions } from './testPlugin'

252
src/testPlugin.ts
View File

@@ -1,4 +1,5 @@
import { SUPPORTED_API_VERSION, validatePlugin } from './validatePlugin'
import semver from 'semver'
import { SUPPORTED_API_RANGE, validatePlugin } from './validatePlugin'
export interface TestNote {
id: string
@@ -24,123 +25,136 @@ export interface TestPluginOptions {
create(note: any): Promise<void>
update(note: any): Promise<void>
delete(id: string): Promise<void>
}
config?: any
}
export const runPluginTests = ({ plugin, adapter }: TestPluginOptions) => {
return {
validatePlugin: (it: any, equal: (a: any, b: any) => void) => {
it('should be a valid plugin', () => {
try {
validatePlugin(plugin)
} catch (e) {
throw new Error('Plugin validation failed')
}
})
it('should have correct apiVersion', () => {
equal(plugin.apiVersion, SUPPORTED_API_VERSION)
})
},
init: (it: any) => {
it('should initialize without errors', async () => {
await adapter.init()
})
},
getAll: (it: any) => {
it('should return an array', async () => {
const notes = await adapter.getAll()
if (!Array.isArray(notes)) {
throw new Error('getAll should return an array')
}
})
},
create: (it: any) => {
it('should create a note without errors', async () => {
const note = createTestNote()
await adapter.create(note)
})
it('created note should be retrievable via getAll()', async () => {
const note = createTestNote('test-create-note')
await adapter.create(note)
const notes = await adapter.getAll()
const found = notes.find((n: any) => n.id === note.id)
if (!found) {
throw new Error('Created note not found')
}
})
},
update: (it: any) => {
it('should update a note without errors', async () => {
const note = createTestNote('test-update-note')
await adapter.create(note)
const updatedNote = { ...note, data: 'Updated data' }
await adapter.update(updatedNote)
})
it('updated note should reflect changes', async () => {
const note = createTestNote('test-update-note-2')
await adapter.create(note)
const updatedNote = { ...note, data: 'Updated data v2' }
await adapter.update(updatedNote)
const notes = await adapter.getAll()
const found = notes.find((n: any) => n.id === note.id)
if (found?.data !== 'Updated data v2') {
throw new Error('Updated note data does not match')
}
})
},
delete: (it: any) => {
it('should delete a note without errors', async () => {
const note = createTestNote('test-delete-note')
await adapter.create(note)
await adapter.delete(note.id)
})
it('deleted note should not be in getAll() results', async () => {
const note = createTestNote('test-delete-note-2')
await adapter.create(note)
await adapter.delete(note.id)
const notes = await adapter.getAll()
const found = notes.find((n: any) => n.id === note.id)
if (found) {
throw new Error('Deleted note still exists')
}
})
},
crudCycle: (it: any) => {
it('should complete full create -> read -> update -> delete cycle', async () => {
const note = createTestNote('test-crud-cycle')
await adapter.create(note)
let notes = await adapter.getAll()
if (!notes.find((n: any) => n.id === note.id)) {
throw new Error('Created note not found')
}
const updatedNote = { ...note, data: 'CRUD update' }
await adapter.update(updatedNote)
notes = await adapter.getAll()
if (
notes.find((n: any) => n.id === note.id)?.data !==
'CRUD update'
) {
throw new Error('Updated note data does not match')
}
await adapter.delete(note.id)
notes = await adapter.getAll()
if (notes.find((n: any) => n.id === note.id)) {
throw new Error('Deleted note still exists')
}
})
},
testConnection(): Promise<boolean>
}
}
export const describePluginTests = (
{ plugin, adapter }: TestPluginOptions,
describe: (name: string, fn: () => void) => void,
it: (name: string, fn: () => void | Promise<void>) => void,
expect: (value: any) => {
toBe: (expected: any) => void
},
) => {
describe('Plugin Validation', () => {
it('should be a valid plugin', () => {
try {
validatePlugin(plugin)
} catch (e) {
throw new Error('Plugin validation failed')
}
})
it('should have correct apiVersion', () => {
if (!semver.satisfies(plugin.apiVersion, SUPPORTED_API_RANGE)) {
throw new Error(
`Plugin apiVersion ${plugin.apiVersion} does not satisfy ${SUPPORTED_API_RANGE}`,
)
}
})
})
describe('Adapter: init()', () => {
it('should initialize without errors', async () => {
await adapter.init()
})
})
describe('Adapter: getAll()', () => {
it('should return an array', async () => {
const notes = await adapter.getAll()
if (!Array.isArray(notes)) {
throw new Error('getAll should return an array')
}
})
})
describe('Adapter: create()', () => {
it('should create a note without errors', async () => {
const note = createTestNote()
await adapter.create(note)
})
it('created note should be retrievable via getAll()', async () => {
const note = createTestNote('test-create-note')
await adapter.create(note)
const notes = await adapter.getAll()
const found = notes.find((n) => n.id === note.id)
if (!found) {
throw new Error('Created note not found')
}
})
})
describe('Adapter: update()', () => {
it('should update a note without errors', async () => {
const note = createTestNote('test-update-note')
await adapter.create(note)
const updatedNote = { ...note, data: 'Updated data' }
await adapter.update(updatedNote)
})
it('updated note should reflect changes', async () => {
const note = createTestNote('test-update-note-2')
await adapter.create(note)
const updatedNote = { ...note, data: 'Updated data v2' }
await adapter.update(updatedNote)
const notes = await adapter.getAll()
const found = notes.find((n) => n.id === note.id)
if (found?.data !== 'Updated data v2') {
throw new Error('Updated note data does not match')
}
})
})
describe('Adapter: delete()', () => {
it('should delete a note without errors', async () => {
const note = createTestNote('test-delete-note')
await adapter.create(note)
await adapter.delete(note.id)
})
it('deleted note should not be in getAll() results', async () => {
const note = createTestNote('test-delete-note-2')
await adapter.create(note)
await adapter.delete(note.id)
const notes = await adapter.getAll()
const found = notes.find((n) => n.id === note.id)
if (found) {
throw new Error('Deleted note still exists')
}
})
})
describe('Adapter: testConnection()', () => {
it('connection test should return true', async () => {
const result = await adapter.testConnection()
expect(result).toBe(true)
})
})
describe('Full CRUD Cycle', () => {
it('should complete full create -> read -> update -> delete cycle', async () => {
const note = createTestNote('test-crud-cycle')
await adapter.create(note)
let notes = await adapter.getAll()
if (!notes.find((n) => n.id === note.id)) {
throw new Error('Created note not found')
}
const updatedNote = { ...note, data: 'CRUD update' }
await adapter.update(updatedNote)
notes = await adapter.getAll()
if (notes.find((n) => n.id === note.id)?.data !== 'CRUD update') {
throw new Error('Updated note data does not match')
}
await adapter.delete(note.id)
notes = await adapter.getAll()
if (notes.find((n) => n.id === note.id)) {
throw new Error('Deleted note still exists')
}
})
})
}

7
src/validatePlugin.ts
View File

@@ -1,6 +1,7 @@
import { z } from 'zod'
import semver from 'semver'
export const SUPPORTED_API_VERSION = '0.3.1'
export const SUPPORTED_API_RANGE = '^0.3.0'
const ConfigFieldSchema = z.object({
key: z.string(),
@@ -23,9 +24,9 @@ const PluginSchema = z.object({
export const validatePlugin = (plugin: unknown) => {
const parsed = PluginSchema.parse(plugin)
if (parsed.apiVersion !== SUPPORTED_API_VERSION) {
if (!semver.satisfies(parsed.apiVersion, SUPPORTED_API_RANGE)) {
throw new Error(
`Plugin API mismatch. Expected ${SUPPORTED_API_VERSION}`,
`Plugin API mismatch. Plugin uses ${parsed.apiVersion}, SDK requires ${SUPPORTED_API_RANGE}`,
)
}

3
tsconfig.json
View File

@@ -8,7 +8,6 @@
"moduleResolution": "Node",
"esModuleInterop": true,
"skipLibCheck": true,
"types": ["vitest/globals"]
},
"include": ["src"]
"include": ["src"],
}